AoIterateName()

Find the next control with the given name and interface

Synopsis:

#include <aoi.h>

const AOICtrl_t *AoIterateName(const char *name, 
                               const char *iname,
                               int32_t version,
                               int32_t *cookie);

Arguments:

name: The name of the control you want to find, set in the control's Name interface. This can be NULL if you want to iterate to either the next available AOI control in the global list (if iname is also NULL), or the next control that has an interface with the given name and minimum version (if iname is not NULL).
iname: The name of an interface that any returned control should contain, or NULL if you want to get the next control with the name specified in name regardless of the interfaces it contains.
version: The minimum version of the interface specified with the iname argument; this is ignored if iname is NULL.
cookie: An opaque variable used to iterate through all available AOI controls to find matching interfaces. For the first call to this function, pass in a pointer to an int32_t containing a zero value. For subsequent calls, pass in the same pointer. You must not modify the value it points to between calls.

Library:

libaoi.so

Description:

This function iterates through all available AOI controls, returning each one that has a given name (if specified) and an interface with the given interface name and version (if specified). Controls are named only if they declare the Name interface in their interfaces list.

It's useful to call this function when you don't want to use AoFindName() because you want to examine the addon's strings (using AoGetStrings()) or interfaces (using AoHasInterface()) before you decide whether to load the DLL. It's also useful for detecting when you have multiple controls with the same name so you can write more robust code that examines the interfaces in each control and picks the best control to use.

Returns:

A pointer to an AOICtrl_t structure for a control that matches the search criteria, or NULL if no such control was found.

Classification:

QNX Neutrino