People familiar with AmigaOS programming will already know about the concept of tag lists which can be used to pass additional arguments to functions or receive additional return values. The Hollywood SDK makes extensive use of this concept so that the capabilities of the individual functions can be easily extended in the future simply by offering new tags.
A tag list is an array of a number of struct hwTagList elements that
is terminated by a last element that has its Tag member set to 0. Many Hollywood
SDK API functions accept such a tag list as their last argument in order to be
extensible. struct hwTagList looks like this:
struct hwTagList
{
ULONG Tag;
union {
ULONG iData;
void *pData;
} Data;
};
|
As you can see, each tag item is accompanied by a data item that can either be an
integer value or a pointer. Tag items can either be used to pass additional parameters
to a function or they can also be used to receive additional return values from a
function by setting the pData pointer to a variable that is to receive an additional
return value. The data that needs to be passed in the iData or pData elements depends
on the tag of course. This is all documented alongside the respective API functions.
Here is an example of how a tag list is used with the hw_SetAudioAdapter() API:
struct hwTagList[3]; t[0].Tag = HWSAATAG_BUFFERSIZE; t[0].Data.iData = 2048; t[1].Tag = HWSAATAG_CHANNELS; t[1].Data.iData = 8; t[2].Tag = 0; error = hw_SetAudioAdapter(self, HWSAAFLAGS_PERMANENT, t); |
In this case, a tag list is used to pass some additional parameters to hw_SetAudioAdapter().