How-To deal with BasicLists, SubTemplateLists, & SubTemplateMultiLists:
Each of the list structures uses a nested list of data. The basic list nests a single information element, while the others use a nested template. The template used for nesting is part of the listed templates sent to the collector when the connection is made, or when the data transfer begins. There is no way to mark a template from this list as one that will be nested, or one that will be used as the highest level template. Each of the templates in the list are treated as equals.
The collector does not learn which template or information element is nested until the data arrives. This requires flexbility in the collectors to handle each of the possible results.
The setting of the internal template has not changed with the addition of the list structures. The internal template is still used to perform the initial decoding of the data that arrives at the collector.
Basic lists are not transcoded in the same way as templates because they contain just one information element, thus having no order, so the data can just be parsed and copied to a buffer.
The question with decoding sub templates becomes, what do we use as an internal template for any sub templates that arrive? The answer is a new structure in fixbuf that pairs external and internal template IDs for use in decoding sub templates. The pairs are added to the session that is used for the connection, using fbSessionAddTemplatePair().
Because the external template IDs are only unique for that session, the collector must know the IDs of the templates that are collected in order to pair an internal template with the external template. As a result, callback functionality has been added to fixbuf to alert the user when a new external template has arrived. The callback functions are stored in the session structure, which manages the templates. fbNewTemplateCallback_fn gives the application a pointer to the template structure, allowing the application to determine the contents of the template, a template ID to identify the incoming template, and the session pointer. This information is sufficient for the application to successfully add template pairs to the session for sub template decoding.
The other callback function, fbTemplateCtxCallback2_fn gives the application the session pointer, the template, the template ID, as well as a context variable that is stored for the application in the template. The callback also gives the user another callback that can be used to free the context variable upon template deletion.
If the application does not use the callback, or does not add any template pairs to the session, then fixbuf will transcode each of the sub templates as if the external and internal template were same. This causes all of the fields sent over the wire to be transcoded into the data buffer on the collecting side. The details of that template are passed up to the collector upon receipt of data so it knows how the data is structured in the buffer.
If the application adds any template pair to the list, then the list will be referenced for each transcode. Any external template the application wishes to process MUST have an entry in the list. There are 3 cases for entries in the list:
There are four scenerios in which the user needs to iterate through the elements in a list, whether to fill in, or process the data: