Item Codes and Item Lists

A number of the MTA SDK routines accept a variable length list of item code arguments. For instance, mtaInit() has the call syntax:

int mtaInit(int item_code, ...)

That is to say, it accepts one or more integer-valued call arguments. These call arguments are referred to as an “item code list” or, more simply, an “item list.” Each item list must be terminated by a call argument with the value 0. As such, the call syntax for mtaInit() can be expressed as

int mtaInit([int item_code[, ...]], 0)

There can be zero or more item codes with non-zero values which must then be followed by an item code with the value zero.

In the MTA SDK, item lists serve two purposes. First, they allow code using the SDK to specify optional behaviors and actions to the SDK. Second, they provide an extension mechanism for future versions of the SDK to extend the functionality of routines through the introduction of new item codes.

However, there is a drawback to the use of item lists; the number of items passed to an SDK routine must be known at compile time. That is, it is difficult if not impossible for a program at run time to adjust the number of item codes that it wishes to pass. In recognition of this limitation, all SDK routines that accept an item code list also accept a pointer to an arbitrary length array of item codes. Such an array is referred to as an “item list array” and is specified with the MTA_ITEM_LIST item code. This mechanism allows programs to dynamically construct the array at run time, while still using a fixed number of arguments at compile time.

The MTA_ITEM_LIST item code is always followed by an additional call argument whose value is a pointer to an array of mta_item_list_t type elements. Each array entry has the following five fields:

The end of the array is signified by an array entry whose item_code field has the value zero (MTA_END_LIST). As an example of using MTA_ITEM_LIST, consider the following mtaInit() call:

istat = mtaInit(MTA_DEBUG_SDK, MTA_DEBUG_OS, MTA_DEBUG_MM, 4,
                MTA_DEBUG_DEQUEUE, MTA_DEBUG_DECODE, 0);

      

In the above call, the decision to enable the listed debug modes is made at compile time. Using an item list array allows the decision to be made at run time as illustrated in the following example:

mta_item_list_t item_list[6];
int index;

index = 0;
if (debug_sdk)
   item_list[index++].item_code = MTA_DEBUG_SDK;
if (debug_os)
   item_list[index++].item_code = MTA_DEBUG_OS;
if (debug_mm)
{
   item_list[index].item_code = MTA_DEBUG_MM;
   item_list[index++].item_length = 4;
}
if (debug_dq)
   item_list[index++].item_code = MTA_DEBUG_DEQUEUE;
if (debug_decode)
   item_list[index++].item_code = MTA_DEBUG_DECODE;
item_list[index].item_code = MTA_END_LIST;
istat = mtaInit(MTA_ITEM_CODE, item_list, 0);

The list of item code arguments must still be terminated with a call argument with value zero. Further, item codes may simultaneously be passed as distinct call arguments and also in item list arrays. For example:

mtaInit(MTA_DEBUG_SDK, MTA_ITEM_LIST, item_list1,
        MTA_INTERACTIVE, MTA_ITEM_LIST, item_list2, 0);

      

In the above, the item codes MTA_DEBUG_SDK, MTA_ITEM_LIST, MTA_INTERACTIVE, and MTA_ITEM_LIST are all explicitly passed as call arguments. Additional item codes are passed via the item list arrays item_list1 and item_list2.

When processing item codes, they are processed from left to right as the call argument list is interpreted. Using the above example, mtaInit() processes MTA_DEBUG_SDK, then MTA_ITEM_LIST, MTA_INTERACTIVE, MTA_ITEM_LIST, and finally the terminating 0 call argument which terminates the item code processing. When processing the first occurrence of MTA_ITEM_LIST, the entries of item_list1 are processed starting with the first entry (index 0), then the second, and so on until an entry with an item code value of 0 is encountered. The same processing occurs for item_list2.

If two item codes set the same underlying option or value, the last processed instance of that item code will prevail. For example, the call:

mtaInit(MTA_DEBUG_ENQUEUE, MTA_DEBUG_MM, 10, 0);

will leave the enqueue debug level set to 10. While the MTA_DEBUG_ENQUEUE item code sets it to 5, the subsequent MTA_DEBUG_MM item code changes the setting to 10.