annotate libpurple/nat-pmp.h @ 18088:c138916a49b3

I think it's reasonable to search through a haystack that is the empty string. This gets rid of the following assertion failure for me: #0 0x00002b7f5ebdccab in raise () from /lib/libc.so.6 #1 0x00002b7f5ebde660 in abort () from /lib/libc.so.6 #2 0x00002b7f5e046b1b in g_logv () from /usr/lib/libglib-2.0.so.0 #3 0x00002b7f5e046bb3 in g_log () from /usr/lib/libglib-2.0.so.0 #4 0x00002b7f5e326746 in purple_markup_find_tag (needle=0x2b7f5e33fb89 "img", haystack=0x11fcf6c "", start=0x7fff51043070, end=0x7fff51043068, attributes=0x7fff51043060) at util.c:1016 #5 0x00002b7f5e2fa9f4 in convert_image_tags (log=0x931a80, msg=0x11fcf60 "<IMG ID=\"1\">") at log.c:709 #6 0x00002b7f5e2fba15 in html_logger_write (log=0x931a80, type=4097, from=0x778e00 "lk80z", time=1181547027, message=0x11fcf60 "<IMG ID=\"1\">") at log.c:1339 #7 0x00002b7f5e2f8fee in purple_log_write (log=0x931a80, type=4097, from=0x778e00 "lk80z", time=1181547027, message=0x11fcf60 "<IMG ID=\"1\">") at log.c:155 #8 0x00002b7f5e2eca6c in purple_conversation_write (conv=0x1041500, who=0xf50ba0 "giantpucepanda", message=0x11ec670 "<IMG ID=\"1\">", flags=4097, mtime=1181547027) at conversation.c:883 #9 0x0000000000452ca5 in pidgin_conv_write_im (conv=0x1041500, who=0x0, message=0x11ec670 "<IMG ID=\"1\">", flags=4097, mtime=1181547027) at gtkconv.c:4827 #10 0x00002b7f5e2ed21e in purple_conv_im_write (im=0x111b170, who=0x0, message=0x11ec670 "<IMG ID=\"1\">", flags=4097, mtime=1181547027)

/**
 * @file nat-pmp.h NAT-PMP Implementation
 * @ingroup core
 *
 * purple
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * Most code in nat-pmp.h copyright (C) 2007, R. Tyler Ballance, bleep, LLC.
 * This file is distributed under the 3-clause (modified) BSD license:
 * Redistribution and use in source and binary forms, with or without modification, are permitted
 * provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this list of conditions and
 * the following disclaimer.
 * Neither the name of the bleep. LLC nor the names of its contributors may be used to endorse or promote
 * products derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 */

#ifndef _PURPLE_NAT_PMP_H
#define _PURPLE_NAT_PMP_H

#include <glib.h>

#define PURPLE_PMP_LIFETIME	3600	/* 3600 seconds */

typedef enum {
	PURPLE_PMP_TYPE_UDP,
	PURPLE_PMP_TYPE_TCP
} PurplePmpType;

/**
 * Initialize nat-pmp
 */
void purple_pmp_init(void);

/**
 *
 */
char *purple_pmp_get_public_ip(void);

/**
 * Remove the NAT-PMP mapping for a specified type on a specified port
 *
 * @param type The PurplePmpType
 * @param privateport The private port on which we are listening locally
 * @param publicport The public port on which we are expecting a response
 * @param lifetime The lifetime of the mapping. It is recommended that this be PURPLE_PMP_LIFETIME.
 *
 * @returns TRUE if succesful; FALSE if unsuccessful
 */
gboolean purple_pmp_create_map(PurplePmpType type, unsigned short privateport, unsigned short publicport, int lifetime);

/**
 * Remove the NAT-PMP mapping for a specified type on a specified port
 *
 * @param type The PurplePmpType
 * @param privateport The private port on which the mapping was previously made
 *
 * @returns TRUE if succesful; FALSE if unsuccessful
 */
gboolean purple_pmp_destroy_map(PurplePmpType type, unsigned short privateport);

#endif