Core API Reference

Updated: May 06, 2022

The Addon Interfaces (AOI) library core API contains the functions and data types for accessing addon interfaces, holding their library files (DLLs) in memory, and looking up symbols in these files.

CAUTION:
An important aspect of using the core API is function safety. This refers to the situations when it is safe to use the API functions. Be sure to read the next section.
To access, hold, and use interfaces through the AOI library, an application must do these steps:
  1. Register any interfaces that may be of use.

    The application can use the AoAdd*() functions to register all interfaces found in either an addon library file (DLL), the files in a directory, or a list of static interfaces defined in the code. These functions add the interfaces to a list and make them accessible through a returned control handle.

    Calling AoLoadConfig() applies the configuration settings read from a data structure to the interfaces, in addition to registering them.

  2. Select the best implementations.

    The application may want to pick the interface implementations best suited for certain tasks such as handling media content. For these cases, the AoFind*() functions can report the ratings of specific interfaces for a given file extension, media format, or mimetype. These functions also return control handles for accessing the interfaces.

  3. Hold the controls containing any required interfaces.

    Calling AoHold() informs the AOI library that the application is using the interfaces in a control and hence, the corresponding addon DLL must be kept in memory. Each thread that needs to use the control should call this function.

  4. Retrieve the interfaces.

    The AoGet*Interface() functions let the application get an interface's metadata structure or a pointer to an interface. Often, interface pointers are pointers to function tables, but they can refer to anything else. Any application can use an interface if it knows what this pointer refers to.

  5. Use the interfaces.

    The application can then use the interfaces, by invoking their functions and accessing their data, to do whatever it needs to do. The AOI library API provides helper functions, AoFindString() and AoSearchString(), for accessing the strings exposed by addons and the settings of these strings.

  6. Release the controls.

    When the application has finished using the interfaces in a control, it should call AoRelease() for each hold it placed (i.e., in each thread that called AoHold()). This ensures that the control's reference count returns to zero and so, the library can remove the interfaces when requested.

  7. De-register the interfaces for released controls.

    When it no longer needs a control handle and has released the control, the application can call AoRemove() to remove the control's interfaces from the list and clean up their resources.