Name
SerializeItem -- serialize next item (V9.0)
Synopsis
int ok = SerializeItem(APTR handle, struct hwSerializeItemInfo *key,
             struct hwSerializeItemInfo *val, struct hwTagList *tags);
Function
This function must serialize the item specified by key and val using the serializer specified by handle. Items must always be serialized as key-value pairs which is why SerializeItem() will always be passed those two arguments. handle will be a serializer created by InitSerializer().

Both, the key and the value of the item to serialize are passed using a struct hwSerializeItemInfo pointer. This structure looks like this:

 
struct hwSerializeItemInfo
{
    int Type;
    APTR Data;
    int Length;
    ULONG Flags;
};

Here is an explanation of the individual structure members:

Type:
This will be set to the type of the key and value to be serialized. This will be one of the following types:

HWSERIALIZETYPE_DOUBLE:
Key or value is a double number. Data will contain a pointer to a double containing that number.

HWSERIALIZETYPE_STRING:
Key or value is a string. Data will contain a pointer to this string. The string needn't be NULL-terminated because Length will be set to the string length in bytes. Note that strings passed as values may also contain binary data. Keys, however, will always be text. If Length is 0 Data will be NULL as well.

HWSERIALIZETYPE_TABLE:
Value is a table. Note that this can only be used for values. Tables cannot be used as keys. Data will be NULL. Note that this item will be sent to you twice: When a new table is to be serialized, Length will be set to 1. After that all items of that table will be serialized and then the initial table item will be sent to you again, but now with Length set to 0. Thus, the Length field can be interpreted as opening (1) or closing (0) the table that is to be serialized.

HWSERIALIZETYPE_FUNCTION:
Value is a function. Note that this can only be used for values. Functions cannot be used as keys. Data will be set to a memory buffer containing the byte code of the function. Length will be set to the length of the byte code in bytes.

Data:
Depends on the Type member. See above.

Length:
Depends on the Type member. See above.

Flags:
This can be a combination of the following flags:

HWSERIALIZEFLAGS_SPARSE:
This will be set for all keys that belong to a sparse table.

HWSERIALIZEFLAGS_BINARY:
This will be set for all keys that belong to a table that has values that use binary data (e.g. functions or strings that have binary data).

Note that to serialize the data, SerializeItem() has to call the writefunc() that was passed to your plugin when Hollywood called your InitSerializer() function. See InitSerializer for details. This function looks like this:

 
int writefunc(APTR data, int len, APTR userdata);

The following arguments must be passed:

data:
The data to serialize.

len:
The length of the data in bytes.

userdata:
The user data that was passed to your InitSerializer() function.

The return value of writefunc() will be the number of bytes successfully written. If this is not the same as len (or any other error has occurred), SerializeItem() should return False to indicate an error.

Inputs
handle
serializer handle allocated by InitSerializer()
key
key of the item to serialize
val
value of the item to serialize
tags
reserved for future use, currently always NULL
Results
ok
return True to indicate success, False to indicate failure

Show TOC