![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Next]](next.gif) |
|
|
|
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.
There are three built-in interfaces:
A context constructor/destructor interface.
It defines these functions:
#include <aoi.h> void *(*Create)(const AOICtrl_t *interfaces);
This function should create and return a new context for the addon.
A new context for the addon.
#include <aoi.h> int32_t (*Destroy)(void *context);
This function should free the context for an addon.
0 if successful.
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:
#include <aoi.h> int32_t (*RateExtension)(const char *ext);
This function should return a rating for the given extension.
A rating from 0 to 100 of how well the addon can handle the given file extension. 100 is the best rating.
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:
#include <aoi.h> int32_t (*RateFormat)(const AODataFormat_t *format);
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.
A rating from 0 to 100 of how well the addon can handle the given media format. 100 is best rating.
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:
#include <aoi.h> int32_t (*RateMimetype)(const char *mimetype);
This function should return a rating for the given mimetype.
A rating between 0 and 100 of how well your addon can handle a given mimetype. 100 is the best rating.
An interface that defines all the functions necessary to implement a one-way byte stream. It defines these functions:
#include <aoi.h>
AOIStream_t *(*Open)(const char *name,
const char *mode);
This function should open the stream with the given name in the mode.
A pointer to an AOIStream_t instance, or NULL if the function can't open the given stream in the given mode.
#include <aoi.h> int32_t (*Close)(AOIStream_t *stream);
This function should close the stream and free any data allocated at open.
0 if successful.
#include <aoi.h>
int64_t (*Sniff)(void *ctx,
void *buf,
int64_t num);
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().
The number of bytes successfully sniffed from the stream.
#include <aoi.h>
int64_t (*Read)(void *ctx,
void *buf,
int64_t num);
This function should read num bytes from the stream at the stream's current file position.
The number of bytes successfully read from the stream.
#include <aoi.h>
int64_t (*Write)(void *ctx,
const void *buf,
int64_t num);
This function should write num bytes to the stream at the stream's current file position.
The number of bytes succesfully written to the stream.
#include <aoi.h>
int64_t (*Seek)(void *ctx,
int64_t offset,
int32_t whence);
This function should seek to the given position in the stream.
The new stream position.
#include <aoi.h> int64_t (*Tell)(void *ctx);
This function should return the current position in the stream.
The current position in the stream.
#include <aoi.h> int64_t (*Length)(void *ctx);
This function should return the length of the stream, in bytes, if known.
The length of the stream.
#include <aoi.h>
int32_t (*SideInfo)(void *context,
char **sideinfo,
int32_t *length);
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.
0 if successful.
An interface that allows your addon to return a rating as to how well it can process a given stream. It defines one function:
#include <aoi.h> int32_t (*RateStream)(AOIStream_t *stream);
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.
A rating from 0 to 100 of how well the addon can handle the stream. 100 is the best rating.
An interface that allows an application to access to your addon's resources. It defines these functions:
#include <aoi.h> const AOResource_t *(*GetResources)(void *ctx);
This function should return all the resources of a DLL for the given context.
 |
The returned resources should be read only. |
An AOResource_t list of resources.
#include <aoi.h>
int32_t (*SetResource)(void *ctx,
const char *resource,
const void *data);
This function should set the value in a specific resource. You should be sure of the type of values you can set.
0 if successful.
There are three built-in interfaces in the Addon Interfaces Library: Unloading, InitializeInterface, and Name.
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.
An interface pointer that points to a string. You need to declare this interface to use AoFindName().
|
|
|