comparison libpurple/protocols/myspace/message.c @ 18895:f732d072b118

Change all code to better match the style of libpurple - use 8-space tabs for indentation everywhere. Spaces are still used for alignment when needed, as described on http://derkarl.org/why_to_tabs.html (ack for [^\t]\t to ensure tabs are only being used for indentation). Lots of vim regexes made this transformation possible. Also cuddled a few braces that I missed before. This is a big commit, but there are no actual code changes.

18894:daedc9647341

static MsimMessage *msim_msg_new_v(va_list argp);

/* Escape codes and associated replacement text, used for protocol message
 * escaping and unescaping. */
static struct MSIM_ESCAPE_REPLACEMENT {
    gchar *code;
    gchar *text;
} msim_escape_replacements[] = {
    { "/1", "/" },
    { "/2", "\\" },
    /* { "/3", "|" }, */        /* Not used here -- only for within arrays */
    { NULL, NULL }
};

/**
 * Unescape or escape a protocol message.
 *

static gchar *
msim_unescape_or_escape(const gchar *original_msg, gboolean escape)
{
	gchar *tmp, *msg;
	guint i;
    struct MSIM_ESCAPE_REPLACEMENT* replacement;

    /* Freed in loop below. */
    msg = g_strdup(original_msg);

	/* Replace each code in msim_replacement_code with
	 * corresponding entry in msim_replacement_text. */
    for (i = 0; (replacement = &msim_escape_replacements[i]); ++i)	{
        gchar *code, *text;

        code = replacement->code;
        text = replacement->text;

        if (!code || !text)
            break;

		if (escape) {
			tmp = str_replace(msg, text, code);
		} else {
			tmp = str_replace(msg, code, text);

	va_start(argp, not_empty);

	if (not_empty) {
		return msim_msg_new_v(argp);
    } else {
		return NULL;
    }
}

/** Create a new message from va_list and its first argument.
 *
 * @param argp A va_list of variadic arguments, already started with va_start(). Will be va_end()'d.

{
	gchar *key, *value;
	MsimMessageType type;
	MsimMessage *msg;

    GString *gs;
    GList *gl;
    MsimMessage *dict;


	/* Begin with an empty message. */
	msg = NULL;

				msg = msim_msg_append(msg, key, type, value);
				break;

			case MSIM_TYPE_BINARY:
                gs = va_arg(argp, GString *);

                g_return_val_if_fail(gs != NULL, FALSE);

                /* msim_msg_free() will free this GString the caller created. */
                msg = msim_msg_append(msg, key, type, gs);
                break;
            
            case MSIM_TYPE_LIST:
                gl = va_arg(argp, GList *);

                g_return_val_if_fail(gl != NULL, FALSE);

                msg = msim_msg_append(msg, key, type, gl);
                break;

            case MSIM_TYPE_DICTIONARY:
                dict = va_arg(argp, MsimMessage *);

                g_return_val_if_fail(dict != NULL, FALSE);

                msg = msim_msg_append(msg, key, type, dict);
                break;

			default:
				purple_debug_info("msim", "msim_send: unknown type %d\n", type);
				break;
		}
	} while(key);
	va_end(argp);	

	return msg;
}

/** Perform a deep copy on a GList * of gchar * strings. Free with msim_msg_list_free(). */
GList *
msim_msg_list_copy(GList *old)
{
    GList *new_list;

    new_list = NULL;

    /* Deep copy (g_list_copy is shallow). Copy each string. */
    for (; old != NULL; old = g_list_next(old)) {
        new_list = g_list_append(new_list, g_strdup(old->data));
    }

    return new_list;
}

/** Free a GList * of gchar * strings. */
void
msim_msg_list_free(GList *l)
{

    for (; l != NULL; l = g_list_next(l)) {
        g_free((gchar *)(l->data));
    }
    g_list_free(l);
}

/** Parse a |-separated string into a new GList. Free with msim_msg_list_free(). */
GList *
msim_msg_list_parse(const gchar *raw)
{
    gchar **array;
    GList *list;
    guint i;

    array = g_strsplit(raw, "|", 0);
    list = NULL;

    /* TODO: escape/unescape /3 <-> | within list elements */
    
    for (i = 0; array[i] != NULL; ++i) {
        list = g_list_append(list, g_strdup(array[i]));
    }

    g_strfreev(array);

    return list;
}

/** Clone an individual element.
 *
 * @param data MsimMessageElement * to clone.

{
	MsimMessageElement *elem;
	MsimMessage **new;
	gpointer new_data;
				
    GString *gs;
    MsimMessage *dict;

	elem = (MsimMessageElement *)data;
	new = (MsimMessage **)user_data;

	switch (elem->type) {

		case MSIM_TYPE_RAW:
		case MSIM_TYPE_STRING:
			new_data = g_strdup((gchar *)elem->data);
			break;

        case MSIM_TYPE_LIST:
            new_data = (gpointer)msim_msg_list_copy((GList *)(elem->data));
            break;

		case MSIM_TYPE_BINARY:
            gs = (GString *)elem->data;

            new_data = g_string_new_len(gs->str, gs->len);
			break;
        case MSIM_TYPE_DICTIONARY:
            dict = (MsimMessage *)elem->data;

            new_data = msim_msg_clone(dict);
            break;

		default:
			purple_debug_info("msim", "msim_msg_clone_element: unknown type %d\n", elem->type);
			g_return_if_fail(NULL);
	}

{
	MsimMessage *new;

	if (old == NULL) {
		return NULL;
    }

	new = msim_msg_new(FALSE);

	g_list_foreach(old, msim_msg_clone_element, &new);

 * element itself with g_free() (see msim_msg_free_element()).
 */
void
msim_msg_free_element_data(MsimMessageElement *elem)
{
    switch (elem->type) {
		case MSIM_TYPE_BOOLEAN:
		case MSIM_TYPE_INTEGER:
			/* Integer value stored in gpointer - no need to free(). */
			break;

			/* Free the GString itself and the binary data. */
			g_string_free((GString *)elem->data, TRUE);
			break;

		case MSIM_TYPE_DICTIONARY:
            msim_msg_free((MsimMessage *)elem->data);
			break;
			
		case MSIM_TYPE_LIST:
            g_list_free((GList *)elem->data);
			break;

		default:
			purple_debug_info("msim", "msim_msg_free_element_data: "
                    "not freeing unknown type %d\n", elem->type);
			break;
	}
}

/** Free an individual message element.

{
	MsimMessageElement *elem;

	elem = (MsimMessageElement *)data;

    msim_msg_free_element_data(elem);

	g_free(elem);
}

/** Free a complete message. */

	if (!msg) {
		/* already free as can be */
		return;
	}

    msim_msg_dump("msim_msg_free: freeing %s", msg);

	g_list_foreach(msg, msim_msg_free_element, NULL);
	g_list_free(msg);
}

{
	gchar *raw;
	gboolean success;
	
	raw = msim_msg_pack(msg);
    g_return_val_if_fail(raw != NULL, FALSE);
	success = msim_send_raw(session, raw);
	g_free(raw);

	msim_msg_dump("msim_msg_send()ing %s\n", msg);
	

msim_send(MsimSession *session, ...)
{
	gboolean success;
	MsimMessage *msg;
	va_list argp;
    
	va_start(argp, session);
	msg = msim_msg_new_v(argp);

	/* Actually send the message. */
	success = msim_msg_send(session, msg);

 * @param type An MSIM_TYPE_* code.
 * @param data Pointer to data, see below.
 *
 * @return The new message - must be assigned to as with GList*. For example:
 *
 * 		msg = msim_msg_append(msg, ...)
 *
 * The data parameter depends on the type given:
 *
 * * MSIM_TYPE_INTEGER: Use GUINT_TO_POINTER(x).
 *

}

/** Insert a new element into a message, before the given element name.
 *
 * @param name_before Name of the element to insert the new element before. If 
 * 					  could not be found or NULL, new element will be inserted at end.
 *
 * See msim_msg_append() for usage of other parameters, and an important note about return value.
 */
MsimMessage *
msim_msg_insert_before(MsimMessage *msg, const gchar *name_before, 
		const gchar *name, MsimMessageType type, gpointer data)
{
	MsimMessageElement *new_elem;
	GList *node_before;

	new_elem = msim_msg_element_new(name, type, data);	

	node_before = msim_msg_get_node(msg, name_before);

	return g_list_insert_before(msg, node_before, new_elem);
}

/** Pack a string using the given GFunc and seperator.
 * Used by msim_msg_dump() and msim_msg_pack().
 */
gchar *
msim_msg_pack_using(MsimMessage *msg, 
        GFunc gf, 
        const gchar *sep, 
		const gchar *begin, const gchar *end)
{
	gchar **strings;
	gchar **strings_tmp;
	gchar *joined;

{
	MsimMessageElement *elem;
	gchar *string;
	GString *gs;
	gchar *binary;
	gchar ***items;	 	/* wow, a pointer to a pointer to a pointer */
    
    gchar *s;
    GList *gl;
    guint i;

	elem = (MsimMessageElement *)data;
	items = user_data;

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			string = g_strdup_printf("%s(integer): %d", elem->name, 
                    GPOINTER_TO_UINT(elem->data));
			break;

		case MSIM_TYPE_RAW:
			string = g_strdup_printf("%s(raw): %s", elem->name, 
                    elem->data ? (gchar *)elem->data : "(NULL)");
			break;

		case MSIM_TYPE_STRING:
			string = g_strdup_printf("%s(string): %s", elem->name, 
                    elem->data ? (gchar *)elem->data : "(NULL)");
			break;

		case MSIM_TYPE_BINARY:
			gs = (GString *)elem->data;
			binary = purple_base64_encode((guchar*)gs->str, gs->len);

			string = g_strdup_printf("%s(boolean): %s", elem->name,
					elem->data ? "TRUE" : "FALSE");
			break;

		case MSIM_TYPE_DICTIONARY:
            if (!elem->data)
                s = g_strdup("(NULL)");
            else
                s = msim_msg_dump_to_str((MsimMessage *)elem->data);

            if (!s)
                s = g_strdup("(NULL, couldn't msim_msg_dump_to_str)");

            string = g_strdup_printf("%s(dict): %s", elem->name, s);

            g_free(s);
			break;
			
		case MSIM_TYPE_LIST:
            gs = g_string_new("");
            g_string_append_printf(gs, "%s(list): \n", elem->name);

            i = 0;
            for (gl = (GList *)elem->data; gl != NULL; gl = g_list_next(gl))
            {
                g_string_append_printf(gs, " %d. %s\n", i, (gchar *)(gl->data));
                ++i;
            }
            
            string = gs->str;
			break;

		default:
			string = g_strdup_printf("%s(unknown type %d", 
                    elem->name ? elem->name : "(NULL)", elem->type);
			break;
	}

	**items = string;
	++(*items);

 * @param fmt_string A static string, in which '%s' will be replaced.
 */
void 
msim_msg_dump(const gchar *fmt_string, MsimMessage *msg)
{
    gchar *debug_str;

    g_return_if_fail(fmt_string != NULL);

    debug_str = msim_msg_dump_to_str(msg);
    
    g_return_if_fail(debug_str != NULL);

    purple_debug_info("msim_msg_dump", "debug_str=%s\n", debug_str);


	purple_debug_info("msim", fmt_string, debug_str);

	g_free(debug_str);

	} else {
		debug_str = msim_msg_pack_using(msg, msim_msg_debug_string_element, 
				"\n", "<MsimMessage: \n", "\n/MsimMessage>");
	}

    return debug_str;
}

/** Return a message element data as a new string for a raw protocol message, converting from other types (integer, etc.) if necessary.
 *
 * @return const gchar * The data as a string, or NULL. Caller must g_free().

 * msim_msg_get_string() if you want a string, which in some cases is same as this.
 */
gchar *
msim_msg_pack_element_data(MsimMessageElement *elem)
{
    GString *gs;
    GList *gl;

    g_return_val_if_fail(elem != NULL, NULL);

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return g_strdup_printf("%d", GPOINTER_TO_UINT(elem->data));

			/* Not un-escaped - this is a raw element, already escaped if necessary. */
			return (gchar *)g_strdup((gchar *)elem->data);

		case MSIM_TYPE_STRING:
			/* Strings get escaped. msim_escape() creates a new string. */
            g_return_val_if_fail(elem->data != NULL, NULL);
			return elem->data ? msim_escape((gchar *)elem->data) :
                g_strdup("(NULL)");

		case MSIM_TYPE_BINARY:
            gs = (GString *)elem->data;
            /* Do not escape! */
            return purple_base64_encode((guchar *)gs->str, gs->len);

		case MSIM_TYPE_BOOLEAN:
			/* Not used by messages in the wire protocol * -- see msim_msg_pack_element.
             * Only used by dictionaries, see msim_msg_pack_element_dict. */
            return elem->data ? g_strdup("On") : g_strdup("Off");

		case MSIM_TYPE_DICTIONARY:
			/* TODO: pack using k=v\034k2=v2\034... */
			return msim_msg_pack_dict((MsimMessage *)elem->data);
			
		case MSIM_TYPE_LIST:
			/* Pack using a|b|c|d|... */
            gs = g_string_new("");

            for (gl = (GList *)elem->data; gl != NULL; gl = g_list_next(gl)) {
                g_string_append_printf(gs, "%s", (gchar*)(gl->data));
                
                /* All but last element is separated by a bar. */
                if (g_list_next(gl)) 
                    g_string_append(gs, "|");
            }
            
            return gs->str;

		default:
			purple_debug_info("msim", "field %s, unknown type %d\n", 
                    elem->name ? elem->name : "(NULL)", 
                    elem->type);
			return NULL;
	}
}

/** Pack an element into its protcol representation inside a dictionary.

 * See msim_msg_pack_element().
 */
static void
msim_msg_pack_element_dict(gpointer data, gpointer user_data)
{
    MsimMessageElement *elem;
    gchar *string, *data_string, ***items;

    elem = (MsimMessageElement *)data;
    items = (gchar ***)user_data;

	/* Exclude elements beginning with '_' from packed protocol messages. */
	if (elem->name[0] == '_') {
		return;
	}

	data_string = msim_msg_pack_element_data(elem);

    g_return_if_fail(data_string != NULL);

	switch (elem->type) {
		/* These types are represented by key name/value pairs (converted above). */
		case MSIM_TYPE_INTEGER:
		case MSIM_TYPE_RAW:
		case MSIM_TYPE_STRING:
		case MSIM_TYPE_BINARY:
		case MSIM_TYPE_DICTIONARY:
		case MSIM_TYPE_LIST:
		case MSIM_TYPE_BOOLEAN:     /* Boolean is On or Off */
			string = g_strconcat(elem->name, "=", data_string, NULL);
			break;

		default:
			g_free(data_string);

 * @return A string; caller must g_free().
 */
gchar *
msim_msg_pack_dict(MsimMessage *msg)
{
    g_return_val_if_fail(msg != NULL, NULL);

    return msim_msg_pack_using(msg, msim_msg_pack_element_dict, "\034", "", "");
}

/** 
 * Parse a raw protocol message string into a MsimMessage *.
 *

 */
MsimMessage *
msim_parse(gchar *raw)
{
	MsimMessage *msg;
    gchar *token;
    gchar **tokens;
    gchar *key;
    gchar *value;
    int i;

    g_return_val_if_fail(raw != NULL, NULL);

    purple_debug_info("msim", "msim_parse: got <%s>\n", raw);

    key = NULL;

    /* All messages begin with a \. */
    if (raw[0] != '\\' || raw[1] == 0) {
        purple_debug_info("msim", "msim_parse: incomplete/bad string, "
                "missing initial backslash: <%s>\n", raw);
        /* XXX: Should we try to recover, and read to first backslash? */

        g_free(raw);
        return NULL;
    }

    msg = msim_msg_new(FALSE);

    for (tokens = g_strsplit(raw + 1, "\\", 0), i = 0; 
            (token = tokens[i]);
            i++) {
#ifdef MSIM_DEBUG_PARSE
        purple_debug_info("msim", "tok=<%s>, i%2=%d\n", token, i % 2);
#endif
        if (i % 2) {
			/* Odd-numbered ordinal is a value. */

			value = token;
		
			/* Incoming protocol messages get tagged as MSIM_TYPE_RAW, which

			 * convert to appropriate types for caller, and handle unescaping if needed. */
			msg = msim_msg_append(msg, g_strdup(key), MSIM_TYPE_RAW, g_strdup(value));
#ifdef MSIM_DEBUG_PARSE
			purple_debug_info("msim", "insert string: |%s|=|%s|\n", key, value);
#endif
        } else {
			/* Even numbered indexes are key names. */
            key = token;
        }
    }
    g_strfreev(tokens);

    /* Can free now since all data was copied to hash key/values */
    g_free(raw);

    return msg;
}

/**
 * Parse a \x1c-separated "dictionary" of key=value pairs into a hash table.
 *
 * @param body_str The text of the dictionary to parse. Often the
 *                  value for the 'body' field.
 *
 * @return Hash table of the keys and values. Must g_hash_table_destroy() when done.
 */
GHashTable *
msim_parse_body(const gchar *body_str)
{
    GHashTable *table;
    gchar *item;
    gchar **items;
    gchar **elements;
    guint i;

    g_return_val_if_fail(body_str != NULL, NULL);

    table = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, g_free);
 
    for (items = g_strsplit(body_str, "\x1c", 0), i = 0; 
        (item = items[i]);
        i++) {
        gchar *key, *value;

        elements = g_strsplit(item, "=", 2);

        key = elements[0];
        if (!key) {
            purple_debug_info("msim", "msim_parse_body(%s): null key\n", 
					body_str);
            g_strfreev(elements);
            break;
        }

        value = elements[1];
        if (!value) {
            purple_debug_info("msim", "msim_parse_body(%s): null value\n", 
					body_str);
            g_strfreev(elements);
            break;
        }

#ifdef MSIM_DEBUG_PARSE
        purple_debug_info("msim", "-- %s: %s\n", key ? key : "(NULL)", 
                value ? value : "(NULL)");
#endif

        /* XXX: This overwrites duplicates. */
        /* TODO: make the GHashTable values be GList's, and append to the list if 
         * there is already a value of the same key name. This is important for
         * the WebChallenge message. */
        g_hash_table_insert(table, g_strdup(key), g_strdup(value));
        
        g_strfreev(elements);
    }

    g_strfreev(items);

    return table;
}

/** Search for and return the node in msg, matching name, or NULL. 
 *
 * @param msg Message to search within.

		elem = i->data;
		g_return_val_if_fail(elem != NULL, NULL);

		if (strcmp(elem->name, name) == 0) {
			return i;
        }
	}
	return NULL;
}

/** Return the first MsimMessageElement * with given name in the MsimMessage *. 

	GList *node;

	node = msim_msg_get_node(msg, name);
	if (node) {
		return (MsimMessageElement *)node->data;
    } else {
		return NULL;
    }
}

/** Return the data of an element of a given name, as a string.
 *
 * @param name Name of element.

msim_msg_get_string(MsimMessage *msg, const gchar *name)
{
	MsimMessageElement *elem;

	elem = msim_msg_get(msg, name);
    g_return_val_if_fail(elem != NULL , NULL);

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return g_strdup_printf("%d", GPOINTER_TO_UINT(elem->data));

/** Return an element as a new list. Caller frees with msim_msg_list_free(). */
GList *
msim_msg_get_list(MsimMessage *msg, const gchar *name)
{
    MsimMessageElement *elem;

    elem = msim_msg_get(msg, name);
    if (!elem) {
        return NULL;
    }

    switch (elem->type) {
        case MSIM_TYPE_LIST:
            return msim_msg_list_copy((GList *)elem->data);

        case MSIM_TYPE_RAW:
            return msim_msg_list_parse((gchar *)elem->data);

        default:
            purple_debug_info("msim_msg_get_list", "type %d unknown, name %s\n",
                    elem->type, name ? name : "(NULL)");
            return NULL;
    }
}

/** Parse a \034-deliminated and =-separated string into a dictionary. TODO */
MsimMessage *
msim_msg_dictionary_parse(gchar *raw)
{
    /* TODO - get code from msim_parse_body, but parse into MsimMessage */
    return NULL;
}

/** Return an element as a new dictionary. Caller frees with msim_msg_free(). */
MsimMessage *
msim_msg_get_dictionary(MsimMessage *msg, const gchar *name)
{
    MsimMessageElement *elem;

    elem = msim_msg_get(msg, name);
    if (!elem)
    {
        return NULL;
    }

    switch (elem->type) {
        case MSIM_TYPE_DICTIONARY:
            return msim_msg_clone((MsimMessage *)elem->data);
        
        case MSIM_TYPE_RAW:
            return msim_msg_dictionary_parse((gchar *)elem->data);

        default:
            purple_debug_info("msim_msg_get_dictionary", "type %d unknown, name %s\n",
                    elem->type, name ? name : "(NULL)");
            return NULL;
    }
}

/** Return the data of an element of a given name, as an integer.
 *
 * @param name Name of element.

	elem = msim_msg_get(msg, name);

	if (!elem) {
		return 0;
    }

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return GPOINTER_TO_UINT(elem->data);

msim_msg_get_binary(MsimMessage *msg, const gchar *name, 
		gchar **binary_data, gsize *binary_length)
{
	MsimMessageElement *elem;
				
    GString *gs;

	elem = msim_msg_get(msg, name);
    if (!elem) {
        return FALSE;
    }

	switch (elem->type) {
		case MSIM_TYPE_RAW:
			 /* Incoming messages are tagged with MSIM_TYPE_RAW, and
			 * converted appropriately. They can still be "strings", just they won't

			 */
			*binary_data = (gchar *)purple_base64_decode((const gchar *)elem->data, binary_length);
			return TRUE;

		case MSIM_TYPE_BINARY:
            gs = (GString *)elem->data;

            /* Duplicate data, so caller can g_free() it. */
            *binary_data = g_new0(char, gs->len);
            memcpy(*binary_data, gs->str, gs->len);

            *binary_length = gs->len;

            return TRUE;


			/* Rejected because if it isn't already a GString, have to g_new0 it and
			 * then caller has to ALSO free the GString! 
			 *

18895:f732d072b118

static MsimMessage *msim_msg_new_v(va_list argp);

/* Escape codes and associated replacement text, used for protocol message
 * escaping and unescaping. */
static struct MSIM_ESCAPE_REPLACEMENT {
	gchar *code;
	gchar *text;
} msim_escape_replacements[] = {
	{ "/1", "/" },
	{ "/2", "\\" },
	/* { "/3", "|" }, */      /* Not used here -- only for within arrays */
	{ NULL, NULL }
};

/**
 * Unescape or escape a protocol message.
 *

static gchar *
msim_unescape_or_escape(const gchar *original_msg, gboolean escape)
{
	gchar *tmp, *msg;
	guint i;
	struct MSIM_ESCAPE_REPLACEMENT* replacement;

	/* Freed in loop below. */
	msg = g_strdup(original_msg);

	/* Replace each code in msim_replacement_code with
	 * corresponding entry in msim_replacement_text. */
	for (i = 0; (replacement = &msim_escape_replacements[i]); ++i) {
		gchar *code, *text;

		code = replacement->code;
		text = replacement->text;

		if (!code || !text)
			break;

		if (escape) {
			tmp = str_replace(msg, text, code);
		} else {
			tmp = str_replace(msg, code, text);

	va_start(argp, not_empty);

	if (not_empty) {
		return msim_msg_new_v(argp);
	} else {
		return NULL;
	}
}

/** Create a new message from va_list and its first argument.
 *
 * @param argp A va_list of variadic arguments, already started with va_start(). Will be va_end()'d.

{
	gchar *key, *value;
	MsimMessageType type;
	MsimMessage *msg;

	GString *gs;
	GList *gl;
	MsimMessage *dict;


	/* Begin with an empty message. */
	msg = NULL;

				msg = msim_msg_append(msg, key, type, value);
				break;

			case MSIM_TYPE_BINARY:
				gs = va_arg(argp, GString *);

				g_return_val_if_fail(gs != NULL, FALSE);

				/* msim_msg_free() will free this GString the caller created. */
				msg = msim_msg_append(msg, key, type, gs);
				break;
			
			case MSIM_TYPE_LIST:
				gl = va_arg(argp, GList *);

				g_return_val_if_fail(gl != NULL, FALSE);

				msg = msim_msg_append(msg, key, type, gl);
				break;

			case MSIM_TYPE_DICTIONARY:
				dict = va_arg(argp, MsimMessage *);

				g_return_val_if_fail(dict != NULL, FALSE);

				msg = msim_msg_append(msg, key, type, dict);
				break;

			default:
				purple_debug_info("msim", "msim_send: unknown type %d\n", type);
				break;
		}
	} while(key);
	va_end(argp);

	return msg;
}

/** Perform a deep copy on a GList * of gchar * strings. Free with msim_msg_list_free(). */
GList *
msim_msg_list_copy(GList *old)
{
	GList *new_list;

	new_list = NULL;

	/* Deep copy (g_list_copy is shallow). Copy each string. */
	for (; old != NULL; old = g_list_next(old)) {
		new_list = g_list_append(new_list, g_strdup(old->data));
	}

	return new_list;
}

/** Free a GList * of gchar * strings. */
void
msim_msg_list_free(GList *l)
{

	for (; l != NULL; l = g_list_next(l)) {
		g_free((gchar *)(l->data));
	}
	g_list_free(l);
}

/** Parse a |-separated string into a new GList. Free with msim_msg_list_free(). */
GList *
msim_msg_list_parse(const gchar *raw)
{
	gchar **array;
	GList *list;
	guint i;

	array = g_strsplit(raw, "|", 0);
	list = NULL;

	/* TODO: escape/unescape /3 <-> | within list elements */
	
	for (i = 0; array[i] != NULL; ++i) {
		list = g_list_append(list, g_strdup(array[i]));
	}

	g_strfreev(array);

	return list;
}

/** Clone an individual element.
 *
 * @param data MsimMessageElement * to clone.

{
	MsimMessageElement *elem;
	MsimMessage **new;
	gpointer new_data;
				
	GString *gs;
	MsimMessage *dict;

	elem = (MsimMessageElement *)data;
	new = (MsimMessage **)user_data;

	switch (elem->type) {

		case MSIM_TYPE_RAW:
		case MSIM_TYPE_STRING:
			new_data = g_strdup((gchar *)elem->data);
			break;

		case MSIM_TYPE_LIST:
			new_data = (gpointer)msim_msg_list_copy((GList *)(elem->data));
			break;

		case MSIM_TYPE_BINARY:
			gs = (GString *)elem->data;

			new_data = g_string_new_len(gs->str, gs->len);
			break;
		case MSIM_TYPE_DICTIONARY:
			dict = (MsimMessage *)elem->data;

			new_data = msim_msg_clone(dict);
			break;

		default:
			purple_debug_info("msim", "msim_msg_clone_element: unknown type %d\n", elem->type);
			g_return_if_fail(NULL);
	}

{
	MsimMessage *new;

	if (old == NULL) {
		return NULL;
	}

	new = msim_msg_new(FALSE);

	g_list_foreach(old, msim_msg_clone_element, &new);

 * element itself with g_free() (see msim_msg_free_element()).
 */
void
msim_msg_free_element_data(MsimMessageElement *elem)
{
	switch (elem->type) {
		case MSIM_TYPE_BOOLEAN:
		case MSIM_TYPE_INTEGER:
			/* Integer value stored in gpointer - no need to free(). */
			break;

			/* Free the GString itself and the binary data. */
			g_string_free((GString *)elem->data, TRUE);
			break;

		case MSIM_TYPE_DICTIONARY:
			msim_msg_free((MsimMessage *)elem->data);
			break;
			
		case MSIM_TYPE_LIST:
			g_list_free((GList *)elem->data);
			break;

		default:
			purple_debug_info("msim", "msim_msg_free_element_data: "
					"not freeing unknown type %d\n", elem->type);
			break;
	}
}

/** Free an individual message element.

{
	MsimMessageElement *elem;

	elem = (MsimMessageElement *)data;

	msim_msg_free_element_data(elem);

	g_free(elem);
}

/** Free a complete message. */

	if (!msg) {
		/* already free as can be */
		return;
	}

	msim_msg_dump("msim_msg_free: freeing %s", msg);

	g_list_foreach(msg, msim_msg_free_element, NULL);
	g_list_free(msg);
}

{
	gchar *raw;
	gboolean success;
	
	raw = msim_msg_pack(msg);
	g_return_val_if_fail(raw != NULL, FALSE);
	success = msim_send_raw(session, raw);
	g_free(raw);

	msim_msg_dump("msim_msg_send()ing %s\n", msg);
	

msim_send(MsimSession *session, ...)
{
	gboolean success;
	MsimMessage *msg;
	va_list argp;
	
	va_start(argp, session);
	msg = msim_msg_new_v(argp);

	/* Actually send the message. */
	success = msim_msg_send(session, msg);

 * @param type An MSIM_TYPE_* code.
 * @param data Pointer to data, see below.
 *
 * @return The new message - must be assigned to as with GList*. For example:
 *
 *     msg = msim_msg_append(msg, ...)
 *
 * The data parameter depends on the type given:
 *
 * * MSIM_TYPE_INTEGER: Use GUINT_TO_POINTER(x).
 *

}

/** Insert a new element into a message, before the given element name.
 *
 * @param name_before Name of the element to insert the new element before. If 
 *                    could not be found or NULL, new element will be inserted at end.
 *
 * See msim_msg_append() for usage of other parameters, and an important note about return value.
 */
MsimMessage *
msim_msg_insert_before(MsimMessage *msg, const gchar *name_before, 
		const gchar *name, MsimMessageType type, gpointer data)
{
	MsimMessageElement *new_elem;
	GList *node_before;

	new_elem = msim_msg_element_new(name, type, data);

	node_before = msim_msg_get_node(msg, name_before);

	return g_list_insert_before(msg, node_before, new_elem);
}

/** Pack a string using the given GFunc and seperator.
 * Used by msim_msg_dump() and msim_msg_pack().
 */
gchar *
msim_msg_pack_using(MsimMessage *msg, 
		GFunc gf, 
		const gchar *sep, 
		const gchar *begin, const gchar *end)
{
	gchar **strings;
	gchar **strings_tmp;
	gchar *joined;

{
	MsimMessageElement *elem;
	gchar *string;
	GString *gs;
	gchar *binary;
	gchar ***items;  /* wow, a pointer to a pointer to a pointer */
	
	gchar *s;
	GList *gl;
	guint i;

	elem = (MsimMessageElement *)data;
	items = user_data;

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			string = g_strdup_printf("%s(integer): %d", elem->name, 
					GPOINTER_TO_UINT(elem->data));
			break;

		case MSIM_TYPE_RAW:
			string = g_strdup_printf("%s(raw): %s", elem->name, 
					elem->data ? (gchar *)elem->data : "(NULL)");
			break;

		case MSIM_TYPE_STRING:
			string = g_strdup_printf("%s(string): %s", elem->name, 
					elem->data ? (gchar *)elem->data : "(NULL)");
			break;

		case MSIM_TYPE_BINARY:
			gs = (GString *)elem->data;
			binary = purple_base64_encode((guchar*)gs->str, gs->len);

			string = g_strdup_printf("%s(boolean): %s", elem->name,
					elem->data ? "TRUE" : "FALSE");
			break;

		case MSIM_TYPE_DICTIONARY:
			if (!elem->data) {
				s = g_strdup("(NULL)");
			} else {
				s = msim_msg_dump_to_str((MsimMessage *)elem->data);
			}

			if (!s) {
				s = g_strdup("(NULL, couldn't msim_msg_dump_to_str)");
			}

			string = g_strdup_printf("%s(dict): %s", elem->name, s);

			g_free(s);
			break;
			
		case MSIM_TYPE_LIST:
			gs = g_string_new("");
			g_string_append_printf(gs, "%s(list): \n", elem->name);

			i = 0;
			for (gl = (GList *)elem->data; gl != NULL; gl = g_list_next(gl)) {
				g_string_append_printf(gs, " %d. %s\n", i, (gchar *)(gl->data));
				++i;
			}
			
			string = gs->str;
			break;

		default:
			string = g_strdup_printf("%s(unknown type %d", 
					elem->name ? elem->name : "(NULL)", elem->type);
			break;
	}

	**items = string;
	++(*items);

 * @param fmt_string A static string, in which '%s' will be replaced.
 */
void 
msim_msg_dump(const gchar *fmt_string, MsimMessage *msg)
{
	gchar *debug_str;

	g_return_if_fail(fmt_string != NULL);

	debug_str = msim_msg_dump_to_str(msg);
	
	g_return_if_fail(debug_str != NULL);

	purple_debug_info("msim_msg_dump", "debug_str=%s\n", debug_str);


	purple_debug_info("msim", fmt_string, debug_str);

	g_free(debug_str);

	} else {
		debug_str = msim_msg_pack_using(msg, msim_msg_debug_string_element, 
				"\n", "<MsimMessage: \n", "\n/MsimMessage>");
	}

	return debug_str;
}

/** Return a message element data as a new string for a raw protocol message, converting from other types (integer, etc.) if necessary.
 *
 * @return const gchar * The data as a string, or NULL. Caller must g_free().

 * msim_msg_get_string() if you want a string, which in some cases is same as this.
 */
gchar *
msim_msg_pack_element_data(MsimMessageElement *elem)
{
	GString *gs;
	GList *gl;

	g_return_val_if_fail(elem != NULL, NULL);

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return g_strdup_printf("%d", GPOINTER_TO_UINT(elem->data));

			/* Not un-escaped - this is a raw element, already escaped if necessary. */
			return (gchar *)g_strdup((gchar *)elem->data);

		case MSIM_TYPE_STRING:
			/* Strings get escaped. msim_escape() creates a new string. */
			g_return_val_if_fail(elem->data != NULL, NULL);
			return elem->data ? msim_escape((gchar *)elem->data) :
				g_strdup("(NULL)");

		case MSIM_TYPE_BINARY:
			gs = (GString *)elem->data;
			/* Do not escape! */
			return purple_base64_encode((guchar *)gs->str, gs->len);

		case MSIM_TYPE_BOOLEAN:
			/* Not used by messages in the wire protocol * -- see msim_msg_pack_element.
			 * Only used by dictionaries, see msim_msg_pack_element_dict. */
			return elem->data ? g_strdup("On") : g_strdup("Off");

		case MSIM_TYPE_DICTIONARY:
			/* TODO: pack using k=v\034k2=v2\034... */
			return msim_msg_pack_dict((MsimMessage *)elem->data);
			
		case MSIM_TYPE_LIST:
			/* Pack using a|b|c|d|... */
			gs = g_string_new("");

			for (gl = (GList *)elem->data; gl != NULL; gl = g_list_next(gl)) {
				g_string_append_printf(gs, "%s", (gchar*)(gl->data));
				
				/* All but last element is separated by a bar. */
				if (g_list_next(gl)) 
					g_string_append(gs, "|");
			}
			
			return gs->str;

		default:
			purple_debug_info("msim", "field %s, unknown type %d\n", 
					elem->name ? elem->name : "(NULL)", 
					elem->type);
			return NULL;
	}
}

/** Pack an element into its protcol representation inside a dictionary.

 * See msim_msg_pack_element().
 */
static void
msim_msg_pack_element_dict(gpointer data, gpointer user_data)
{
	MsimMessageElement *elem;
	gchar *string, *data_string, ***items;

	elem = (MsimMessageElement *)data;
	items = (gchar ***)user_data;

	/* Exclude elements beginning with '_' from packed protocol messages. */
	if (elem->name[0] == '_') {
		return;
	}

	data_string = msim_msg_pack_element_data(elem);

	g_return_if_fail(data_string != NULL);

	switch (elem->type) {
		/* These types are represented by key name/value pairs (converted above). */
		case MSIM_TYPE_INTEGER:
		case MSIM_TYPE_RAW:
		case MSIM_TYPE_STRING:
		case MSIM_TYPE_BINARY:
		case MSIM_TYPE_DICTIONARY:
		case MSIM_TYPE_LIST:
		case MSIM_TYPE_BOOLEAN: /* Boolean is On or Off */
			string = g_strconcat(elem->name, "=", data_string, NULL);
			break;

		default:
			g_free(data_string);

 * @return A string; caller must g_free().
 */
gchar *
msim_msg_pack_dict(MsimMessage *msg)
{
	g_return_val_if_fail(msg != NULL, NULL);

	return msim_msg_pack_using(msg, msim_msg_pack_element_dict, "\034", "", "");
}

/** 
 * Parse a raw protocol message string into a MsimMessage *.
 *

 */
MsimMessage *
msim_parse(gchar *raw)
{
	MsimMessage *msg;
	gchar *token;
	gchar **tokens;
	gchar *key;
	gchar *value;
	int i;

	g_return_val_if_fail(raw != NULL, NULL);

	purple_debug_info("msim", "msim_parse: got <%s>\n", raw);

	key = NULL;

	/* All messages begin with a \. */
	if (raw[0] != '\\' || raw[1] == 0) {
		purple_debug_info("msim", "msim_parse: incomplete/bad string, "
				"missing initial backslash: <%s>\n", raw);
		/* XXX: Should we try to recover, and read to first backslash? */

		g_free(raw);
		return NULL;
	}

	msg = msim_msg_new(FALSE);

	for (tokens = g_strsplit(raw + 1, "\\", 0), i = 0; 
			(token = tokens[i]);
			i++) {
#ifdef MSIM_DEBUG_PARSE
		purple_debug_info("msim", "tok=<%s>, i%2=%d\n", token, i % 2);
#endif
		if (i % 2) {
			/* Odd-numbered ordinal is a value. */

			value = token;
		
			/* Incoming protocol messages get tagged as MSIM_TYPE_RAW, which

			 * convert to appropriate types for caller, and handle unescaping if needed. */
			msg = msim_msg_append(msg, g_strdup(key), MSIM_TYPE_RAW, g_strdup(value));
#ifdef MSIM_DEBUG_PARSE
			purple_debug_info("msim", "insert string: |%s|=|%s|\n", key, value);
#endif
		} else {
			/* Even numbered indexes are key names. */
			key = token;
		}
	}
	g_strfreev(tokens);

	/* Can free now since all data was copied to hash key/values */
	g_free(raw);

	return msg;
}

/**
 * Parse a \x1c-separated "dictionary" of key=value pairs into a hash table.
 *
 * @param body_str The text of the dictionary to parse. Often the
 *                 value for the 'body' field.
 *
 * @return Hash table of the keys and values. Must g_hash_table_destroy() when done.
 */
GHashTable *
msim_parse_body(const gchar *body_str)
{
	GHashTable *table;
	gchar *item;
	gchar **items;
	gchar **elements;
	guint i;

	g_return_val_if_fail(body_str != NULL, NULL);

	table = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, g_free);
 
	for (items = g_strsplit(body_str, "\x1c", 0), i = 0; 
		(item = items[i]);
		i++) {
		gchar *key, *value;

		elements = g_strsplit(item, "=", 2);

		key = elements[0];
		if (!key) {
			purple_debug_info("msim", "msim_parse_body(%s): null key\n", 
					body_str);
			g_strfreev(elements);
			break;
		}

		value = elements[1];
		if (!value) {
			purple_debug_info("msim", "msim_parse_body(%s): null value\n", 
					body_str);
			g_strfreev(elements);
			break;
		}

#ifdef MSIM_DEBUG_PARSE
		purple_debug_info("msim", "-- %s: %s\n", key ? key : "(NULL)", 
				value ? value : "(NULL)");
#endif

		/* XXX: This overwrites duplicates. */
		/* TODO: make the GHashTable values be GList's, and append to the list if 
		 * there is already a value of the same key name. This is important for
		 * the WebChallenge message. */
		g_hash_table_insert(table, g_strdup(key), g_strdup(value));
		
		g_strfreev(elements);
	}

	g_strfreev(items);

	return table;
}

/** Search for and return the node in msg, matching name, or NULL. 
 *
 * @param msg Message to search within.

		elem = i->data;
		g_return_val_if_fail(elem != NULL, NULL);

		if (strcmp(elem->name, name) == 0) {
			return i;
		}
	}
	return NULL;
}

/** Return the first MsimMessageElement * with given name in the MsimMessage *. 

	GList *node;

	node = msim_msg_get_node(msg, name);
	if (node) {
		return (MsimMessageElement *)node->data;
	} else {
		return NULL;
	}
}

/** Return the data of an element of a given name, as a string.
 *
 * @param name Name of element.

msim_msg_get_string(MsimMessage *msg, const gchar *name)
{
	MsimMessageElement *elem;

	elem = msim_msg_get(msg, name);
	g_return_val_if_fail(elem != NULL , NULL);

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return g_strdup_printf("%d", GPOINTER_TO_UINT(elem->data));

/** Return an element as a new list. Caller frees with msim_msg_list_free(). */
GList *
msim_msg_get_list(MsimMessage *msg, const gchar *name)
{
	MsimMessageElement *elem;

	elem = msim_msg_get(msg, name);
	if (!elem) {
		return NULL;
	}

	switch (elem->type) {
		case MSIM_TYPE_LIST:
			return msim_msg_list_copy((GList *)elem->data);

		case MSIM_TYPE_RAW:
			return msim_msg_list_parse((gchar *)elem->data);

		default:
			purple_debug_info("msim_msg_get_list", "type %d unknown, name %s\n",
					elem->type, name ? name : "(NULL)");
			return NULL;
	}
}

/** Parse a \034-deliminated and =-separated string into a dictionary. TODO */
MsimMessage *
msim_msg_dictionary_parse(gchar *raw)
{
	/* TODO - get code from msim_parse_body, but parse into MsimMessage */
	return NULL;
}

/** Return an element as a new dictionary. Caller frees with msim_msg_free(). */
MsimMessage *
msim_msg_get_dictionary(MsimMessage *msg, const gchar *name)
{
	MsimMessageElement *elem;

	elem = msim_msg_get(msg, name);
	if (!elem) {
		return NULL;
	}

	switch (elem->type) {
		case MSIM_TYPE_DICTIONARY:
			return msim_msg_clone((MsimMessage *)elem->data);
		
		case MSIM_TYPE_RAW:
			return msim_msg_dictionary_parse((gchar *)elem->data);

		default:
			purple_debug_info("msim_msg_get_dictionary", "type %d unknown, name %s\n",
					elem->type, name ? name : "(NULL)");
			return NULL;
	}
}

/** Return the data of an element of a given name, as an integer.
 *
 * @param name Name of element.

	elem = msim_msg_get(msg, name);

	if (!elem) {
		return 0;
	}

	switch (elem->type) {
		case MSIM_TYPE_INTEGER:
			return GPOINTER_TO_UINT(elem->data);

msim_msg_get_binary(MsimMessage *msg, const gchar *name, 
		gchar **binary_data, gsize *binary_length)
{
	MsimMessageElement *elem;
				
	GString *gs;

	elem = msim_msg_get(msg, name);
	if (!elem) {
		return FALSE;
	}

	switch (elem->type) {
		case MSIM_TYPE_RAW:
			 /* Incoming messages are tagged with MSIM_TYPE_RAW, and
			 * converted appropriately. They can still be "strings", just they won't

			 */
			*binary_data = (gchar *)purple_base64_decode((const gchar *)elem->data, binary_length);
			return TRUE;

		case MSIM_TYPE_BINARY:
			gs = (GString *)elem->data;

			/* Duplicate data, so caller can g_free() it. */
			*binary_data = g_new0(char, gs->len);
			memcpy(*binary_data, gs->str, gs->len);

			*binary_length = gs->len;

			return TRUE;


			/* Rejected because if it isn't already a GString, have to g_new0 it and
			 * then caller has to ALSO free the GString! 
			 *