Caution: This version of this document is no longer maintained. For the latest documentation, see


Search for a specific interface and hold its control


#include <aoi.h>

const AOICtrl_t *AoIterateHoldGet(const char *name,
                                  const int32_t version,
                                  int32_t *cookie,
                                  void **interface);


The name of the interface in the control you want to find and hold.
The minimum version of the interface in the control you want to find and hold.
An opaque variable used to control the iteration through the list of controls. Set this parameter to 0 on the first call to this function.
The returned interface within the held control that meets the search critera.



This function iterates through the global list of controls, returning each control that has the given interface name with the minimum version number. Unlike AoIterate(), it also holds the control returned, and sets *interface to the interface you're looking for. The first time that you call this function, you should set the value in *cookie to 0. You can keep calling this function until it returns NULL. If name is NULL, AoIterate() iterates through all available controls.

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


A pointer to an AOICtrl_t structure for each control that contains the interface name with a minimum version. The interface parameter is set to the interface that meets the search critera.

When there are no remaining controls that contain a matching interface, this function returns NULL.


QNX Neutrino

Interrupt handler No
Signal handler No
Thread No

See also:

AOICtrl_t, AoRelease(), AoIterate(), AoHold()