Appendix: Implemented Interfaces

This chapter provides an overview of interfaces that have been defined for use with the Addon Interfaces Library. These interfaces define functions for commonly required functionality. To use these interfaces to create your own addon, you must implement the functions they define. If you use an interface, you should implement all its defined functions.

AOStreamer
An interface containing all the functions necessary to implement a one-way byte stream.
AODeConstructor
A context constructor/destructor interface.
AOStreamInspector
An interface that allows your addon to return a rating as to how well it can process a given stream.
AOFormatInspector
An interface that allows your addon to return a rating as to how well it can process data in the given media format.
AOExtInspector
An interface that allows your addon to return a rating as to how well it can process the given file extension.
AOMimetypeInspector
An interface that allows your addon to return a rating as to how well it can process data with the given mimetype.
AOResourceAccess
An interface that allows an application to access your addon's resources.

Built-in Interfaces

There are three built-in interfaces:

Unloading
This interface gives controls that access hardware a chance to leave that hardware in a stable state before being unloaded.
InitializeInterface
This interface allows DLLs to create or choose certain interfaces at runtime instead of at compile time.
Name
An interface pointer that points to a string. You need to declare this interface to use AoFindName().

AODeConstructor

A context constructor/destructor interface.

It defines these functions:

Create()

Synopsis

#include <aoi.h>

void *(*Create)(const AOICtrl_t *interfaces);

Arguments

interfaces
A pointer to an AOICtrl_t structure for the control for the created interface.

Description

This function should create and return a new context for the addon.

Returns

A new context for the addon.

Destroy()

Synopsis

#include <aoi.h>

int32_t (*Destroy)(void *context);

Arguments

context
The addon context you want to destroy.

Description

This function should free the context for an addon.

Returns

0 if successful.

AOExtInspector

An interface that allows your addon to return a rating as to how well it can process the given file extension. It defines one function:

RateExtension()

Synopsis

#include <aoi.h>

int32_t (*RateExtension)(const char *ext);

Arguments

ext
The file extension you want to rate.

Description

This function should return a rating for the given extension.

Returns

A rating from 0 to 100 of how well the addon can handle the given file extension. 100 is the best rating.

AOFormatInspector

An interface that allows your addon to return a rating as to how well it can process data in the given media format. It defines one function:

RateFormat()

Synopsis

#include <aoi.h>

int32_t (*RateFormat)(const AODataFormat_t *format);

Arguments

format
The media format you want to rate.

Description

This function should return a rating for the given media format. Usually this function checks the media type and four character code (fourcc). If it has more stringent requirements, it checks the AODataFormat_t's corresponding union members.

Returns

A rating from 0 to 100 of how well the addon can handle the given media format. 100 is best rating.

AOMimetypeInspector

An interface that allows your addon to return a rating as to how well it can process data with the given mimetype. It defines one function:

RateMimetype()

Synopsis

#include <aoi.h>

int32_t (*RateMimetype)(const char *mimetype);

Arguments

mimetype
The mimetype you want to rate.

Description

This function should return a rating for the given mimetype.

Returns

A rating between 0 and 100 of how well your addon can handle a given mimetype. 100 is the best rating.

AOStreamer

An interface that defines all the functions necessary to implement a one-way byte stream. It defines these functions:

Open

Synopsis

#include <aoi.h>

AOIStream_t *(*Open)(const char *name,
                     const char *mode);

Arguments

name
The name of the stream you want to open.
mode
The mode you want to open the stream in. The mode string should match modes for fopen(), such as:
rb
Read binary.
wb
Write binary.

Description

This function should open the stream with the given name in the mode.

Returns

A pointer to an AOIStream_t instance, or NULL if the function can't open the given stream in the given mode.

Close

Synopsis

#include <aoi.h>

int32_t (*Close)(AOIStream_t *stream);

Arguments

stream
The stream you want to close.

Description

This function should close the stream and free any data allocated at open.

Returns

0 if successful.

Sniff()

Synopsis

#include <aoi.h>

int64_t (*Sniff)(void *ctx,
                 void *buf,
                 int64_t num);

Arguments

ctx
The context for the stream you want to read from.
buf
The buffer into which you want to put read bytes.
num
The number of bytes to be read from the beginning of the stream.

Description

This function should nondestructively read num bytes from the beginning of a stream. All streamers should implement this function. Once stream data is read with Read(), you can no longer use Sniff().

Returns

The number of bytes successfully sniffed from the stream.

Read()

Synopsis

#include <aoi.h>

int64_t (*Read)(void *ctx,
                void *buf,
                int64_t num);

Arguments

ctx
The context for the stream you want to read from.
buf
The buffer into which you want to read data.
num
The number of bytes to be read from the stream (the length of buf).

Description

This function should read num bytes from the stream at the stream's current file position.

Returns

The number of bytes successfully read from the stream.

Write()

Synopsis

#include <aoi.h>

int64_t (*Write)(void *ctx,
                 const void *buf,
                 int64_t num);

Arguments

ctx
The context of the stream you want to write to.
buf
The buffer containing the data you want to write to the stream.
num
The number of bytes to be written to the stream (the length of buf).

Description

This function should write num bytes to the stream at the stream's current file position.

Returns

The number of bytes succesfully written to the stream.

Seek()

Synopsis

#include <aoi.h>

int64_t (*Seek)(void *ctx,
                int64_t offset,
                int32_t whence);

Arguments

ctx
The context for the stream you want to seek in.
offset
The offset, in bytes, to which you want to seek.
whence
The position from which to apply the offset; one of:
SEEK_SET
Compute the new file position relative to the start of the file. The value of offset must not be negative.
SEEK_CUR
Compute the new file position relative to the current file position. The value of offset may be positive, negative or zero.
SEEK_END
Compute the new file position relative to the end of the file.

Description

This function should seek to the given position in the stream.

Returns

The new stream position.

Tell()

Synopsis

#include <aoi.h>

int64_t (*Tell)(void *ctx);

Arguments

ctx
The context for the stream you're querying.

Description

This function should return the current position in the stream.

Returns

The current position in the stream.

Length()

Synopsis

#include <aoi.h>

int64_t (*Length)(void *ctx);

Arguments

ctx
The context for the stream.

Description

This function should return the length of the stream, in bytes, if known.

Returns

The length of the stream.

SideInfo()

Synopsis

#include <aoi.h>

int32_t (*SideInfo)(void *context,
                    char **sideinfo,
                    int32_t *length);

Arguments

context
A pointer to the context for the stream you want to retrieve side information from.
sideinfo
The address of a pointer to space where the function can store the side information for the stream.
length
A pointer to a space where the function can store the returned length of the sideinfo parameter.

Description

This function should store the current side information for a stream in the space provided by sideinfo, and set the sideinfo length. Side information can change any time, and often does, as in the case for inline information in streaming audio.

Returns

0 if successful.

AOStreamInspector

An interface that allows your addon to return a rating as to how well it can process a given stream. It defines one function:

RateStream()

Synopsis

#include <aoi.h>

int32_t (*RateStream)(AOIStream_t *stream);

Arguments

stream
A pointer to the AOIStream_t structure for the stream you want to rate.

Description

This function should return a rating for the given stream. This function should only ever call the Sniff() function in the given stream's AOStreamer interface.

Returns

A rating from 0 to 100 of how well the addon can handle the stream. 100 is the best rating.

AOResourceAccess

An interface that allows an application to access to your addon's resources. It defines these functions:

GetResources()

Synopsis

#include <aoi.h>

const AOResource_t *(*GetResources)(void *ctx);

Arguments

ctx
The context for the control you want a list of resources for.

Description

This function should return all the resources of a DLL for the given context.


Note: The returned resources should be read only.

Returns

An AOResource_t list of resources.

SetResource()

Synopsis

#include <aoi.h>

int32_t (*SetResource)(void *ctx,
                       const char *resource,
                       const void *data);

Arguments

ctx
A pointer to the control that contains the resource you want to set.
resource
The resource you want to set.
data
A pointer to the data you want to set the resource to.

Description

This function should set the value in a specific resource. You should be sure of the type of values you can set.

Returns

0 if successful.

Built-in interfaces

There are three built-in interfaces in the Addon Interfaces Library: Unloading, InitializeInterface, and Name.

Unloading and InitializeInterface

These interfaces define functions that manage different hardware configurations when the application initializes and unloads.

InitializeInterface is an interface pointer that points to a (void *(*)(AOInterface_t *)) function. This function is called automatically to determine the actual value of any interface pointer whose initial value was NULL. This allows DLLs to create or choose certain interfaces at runtime instead of at compile time.

Unloading is an interface pointer that points to a (void (*)(void)) function. If you call AoRelease(), and the count reaches zero, the unloading function is called before the DLL is unloaded. This gives controls that access hardware a chance to leave that hardware in a stable state before being unloaded.

Let's say we have an addon that supports two slightly different pieces of hardware. In this case, we want two different HardwareControl interfaces, and we want to use the one that the hardware the user has installed is for. In this case, we set the interface pointer for the HardwareControl interface to NULL, and create a InitializeInterface interface that returns the appropriate interface. Also, we want to do some cleanup on the hardware when its done, so we implement a Unloading interface as well:

static void *InitializeInterface(AOInterface_t *i)
{
        // we only initialize the "HardwareControl" interface
        if (strcmp(i->name,"HardwareControl")!=0) return 0;

        // return the HardwareControlA/BInterface if either type of
        // hardware is found.
        if (hardware_is_type_a)
                return HardwareControlAInterface;
        else
        if (hardware_is_type_b)
                return HardwareControlBInterface;

        // neither piece of hardware found? return 0
        return 0;
}

static void Unloading(void)
{
        // release the hardware, whatever it is
        release_hardware();
}

AOInterface_t my_hardware_interface[] =
{
        {"Name",0,"my_hardware"},
        {"Description",0,"Plugin for my hardware"},
        {"HardwareControl",0,NULL},
        {"InitializeInterface",0,InitializeInterface},
        {"Unloading",0,Unloading},
        ... (other interfaces)
        {0,0,0},
};

The first time an application requests the HardwareControl interface for the above addon, the Addon Interfaces Library sees that the interface pointer is 0, and calls the InitializeInterface() function with the HardwareControl AOInterface_t as its parameter. The InitializeInterface() function recognizes the HardwareControl interface, checks which hardware is available, and returns the appropriate interface pointer.

Later, when the DLL is unloading, or the application is exiting, the Addon Interfaces Library checks to see if the addon has an Unloading interface, and because it does, that function in the addon is called.

Name

An interface pointer that points to a string. You need to declare this interface to use AoFindName().