Implemented Interfaces

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()
Destroy()

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()
Close()
Sniff()
Read()
Write()
Seek()
Tell()
Length()
SideInfo()

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()
SetResource()

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.

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().

Museum

Implemented Interfaces