AoIterateHoldGet()

Find the next interface and hold its control

Synopsis:

#include <aoi.h>

const AOICtrl_t *AoIterateHoldGet(const char *iname,
                                  const int32_t version,
                                  int32_t *cookie,
                                  void **iface);

Arguments:

iname: The name of an interface that any returned control should contain, or NULL if you want to get the next control in the global list.
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.
iface: A pointer to a location for storing the next interface that matches the search criteria and that the library was able to hold the control for.

Library:

libaoi.so

Description:

This function iterates through all available AOI controls, returning each one that has an interface with the given name and minimum version and that could be held. When you first call this function, you should set cookie to point to a zero value. You can then keep calling this function until it returns the control you're looking for, or it returns NULL, which means there are no more controls.

If name is NULL, AoIterateHoldGet() returns the next control in the global list that could be held, without considering the name or version of any of its interfaces.

This is a convenience function that combines AoIterate(), AoHold(), and AoGetInterface(). You must release each control at some point, or you will end up with an incorrect hold count and the DLLs won't be automatically unloaded.

When the function succeeds, meaning that a control with a matching interface could be held, the iface value points to the interface.

Returns:

For the first call, a pointer to an AOICtrl_t structure for the first control containing an interface that matches the name and version values. Subsequent calls return the next control with such an interface, until there are no more controls, at which point the function returns NULL.

Classification:

QNX Neutrino