API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » codecpluginmgr

palmOneCodecPluginMgr.h File Reference

Detailed Description

The Codec Plugin Manager is used to unify all different type of codecs that are available for PalmOne devices and provide a generic API for developers to access these codecs.

Version:
3.0
A typical application would use the library the following way:

Definition in file palmOneCodecPluginMgr.h.

Include dependency graph for palmOneCodecPluginMgr.h:

Go to the source code of this file.

Functions

Function Documentation

Err CodecMgrClose ( UInt16  refNum  ) 

Closes the Codec Plugin Manager library.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
Return values:
Err The library is closed and errNone is returned. If another application is still using the library, a kCodecMgrLibStillOpen error is returned.

Err CodecMgrCreateSession ( UInt16  refNum,
PalmCodecFormat  inputFormat,
void *  inputParamP,
PalmCodecFormat  outputFormat,
void *  outputParamP,
PalmCodecSession *  sessionP 
)

Create a Codec Session. A session is Codec dependent, which means it is up to a Codec to define the structure (if any) pointed by the Session. This function is called by the CodecPluginMgr. At this stage, the CPM has already selected a known format pair from its codec list. The input and output parameters have to match the format they represent. E.g. palmCodecImageJPEG as input uses PalmJPEGEncodeType palmCodecImageJPEG as output uses PalmJPEGDecodeType etc.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
inputFormat,: IN: Input format for this session.
inputParamP,: IN: Parameter associated with the input format. NULL if not needed.
outputFormat,: IN: Output format for this session.
outputParamP,: IN: Parameter associated with the output format. NULL if not needed.
sessionP OUT: Receives the reference to the newly created session. This reference is passed into all future calls for this session.
Return values:
Err errNone if no error.

Err CodecMgrCreateSessionByID ( UInt16  refNum,
PalmCodecFormat  inputFormat,
void *  inputParamP,
PalmCodecFormat  outputFormat,
void *  outputParamP,
UInt32  creatorID,
UInt32  codecID,
PalmCodecSession *  sessionP 
)

Create a Codec Session using Creator and Codec ID. A session is Codec dependent, which means it is up to a Codec to define the structure (if any) pointed by the Session. This function is called by the CodecPluginMgr. At this stage, the CPM has already selected a known format pair from its codec list. The input and output parameters have to match the format they represent. E.g. palmCodecImageJPEG as input uses PalmJPEGEncodeType palmCodecImageJPEG as output uses PalmJPEGDecodeType etc.

This function is used to create a session when a multiple codecs using the same input and output format are available.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
inputFormat,: IN: Input format for this session.
inputParamP,: IN: Parameter associated with the input format. NULL if not needed.
outputFormat,: IN: Output format for this session.
outputParamP,: IN: Parameter associated with the output format. NULL if not needed.
creatorID,: IN: Creator ID of the module containing the codec.
codecID,: IN: Codec ID for a specific codec.
sessionP,: OUT: Receives the reference to the newly created session. This reference is passed into all future calls for this session.
Returns:
errNone if no error.

Err CodecMgrCustomControl ( UInt16  refNum,
PalmCodecSession  session,
UInt32  apiCreator,
UInt32  apiSelector,
void *  valueP,
UInt32 *  valueLenP 
)

Handle a custom call.

The codec identifies the call and its API by a registered creator code and a selector. This allows codec developers to extend the API by defining selectors for their creator code. It also allows driver developers to support selectors (and custom calls) defined by other driver developers.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
session,: IN: Codec session reference received from CodecCreateSession.
apiCreator,: IN: Registered creator code.
apiSelector,: IN: Custom operation to perform.
valueP,: IN: Buffer containing data specific to the operation.
valueLenP,: IN,OUT: Size of the valueP buffer on entry, size of data written to valueP on exit. If NULL, valueP is ignored.
Return values:
Err errNone if no error, kCodecMgrLibNotSupported if not supported.

Err CodecMgrDeleteSession ( UInt16  refNum,
PalmCodecSession *  sessionP 
)

Delete a session. This function has to delete any allocated memory and set the session reference to NULL.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
sessionP,: IN: Pointer to the Codec session reference received from CodecCreateSession.
Return values:
Err errNone if no error.

Err CodecMgrEncodeDecode ( UInt16  refNum,
PalmCodecSession  session,
void *  srcBufferP,
UInt32 *  srcBufferSizeP,
void *  destBufferP,
UInt32 *  destBufferSizeP 
)

Encode or decode a block of data. The format of the source and destination buffers are set in a preceding call to CodecCreateSession and possibly calls to CodecCustomControl. Is is legal for this function to not encode/decode the whole source buffer. For example, if the source buffer contains a non-round number of encoded blocks, and the encoding format requires whole blocks, this call should encode/decode the even number of blocks, and set srcBufferP appropriately to indicate how much of the source data was actually encoded. The caller should then pass the un-encoded piece of the last chunk in on the next call to this function with the next chunk of data appended to the end of it.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
session,: IN: Codec session reference received from CodecCreateSession.
srcBufferP,: IN: The source buffer to be processed.
srcBufferSizeP,: IN,OUT: On input, the size of srcBufferP in bytes. If the whole buffer is not processed, on output srcBufferP is set to the amount of source data that was processed.
destBufferP,: OUT: The destination buffer which receives the encoded/decoded data.
destBufferSizeP,: IN,OUT: On input, the size of destBufferP in bytes, on output the number of bytes of data written.
Return values:
Err errNone if no error

Err CodecMgrEnumerateFormats ( UInt16  refNum,
UInt32 *  formatIteratorP,
PalmCodecFormat *  inputFormatP,
PalmCodecFormat *  outputFormatP,
UInt32 *  creatorIDP,
UInt32 *  codecIDP 
)

Enumerate all supported input and output format pairs. A pair describes what input format is expected and what output format will come out of the Codec. Codecs can accept multiple format pairs. For example, an MP3 Codec might be able to decode only MP3, MP2, and MP1. In this case, the pairs are: [in: MP3 out: PCM codecID: 0] [in: MP2 out: PCM codecID: 0] [in: MP1 out: PCM codecID: 0]

The Codec ID is used if multiple codecs within the same PRC have the exact same input and output formats. For example, a DSP filter bank might specify PCM as both the input and output for every codec. Codec ID helps differentiate between these Codecs (Low-Pass, High-Pass, Band-Pass...). A Codec ID set to 0 (palmNULLCodecID) means that there is no need to look for a particular codec (for example, if there is only one codec in the PRC).

Pass a formatIteratorP of palmCodecIteratorStart to get the first pair. formatIteratorP will be updated to the next item. When returning the last format pair, the formatIteratorP will be set to palmCodecIteratorStop.

Sample:

PalmCodecFormat inputFormat, outputFormat; UInt32 codecID; UInt32 formatIterator = palmCodecIteratorStart; while (formatIterator != palmCodecIteratorStop) { if ((err = CodecEnumerateSupportedFormats(&formatIterator, &inputFormat, &outputFormat, &codecID)) != errNone) { // Do something with the format pair } else { // handle error... possibly by breaking out of the loop } }

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
formatIteratorP,: IN,OUT: Reference to the last entry enumerated Pass palmCodecIteratorStart to get the first entry. This is updated on return to reference the next entry or set to palmCodecIteratorStop if last directory entry.
inputFormatP,: IN: Receives the input format entry specified with formatIteratorP.
outputFormatP,: IN: Receives the output format entry specified with formatIteratorP.
creatorIDP,: IN: Pointer to the location where the creator ID associated with the current formatIteratorP entry is stored. Pass NULL to ignore this value for each codec.
codecIDP,: IN: Pointer to the location where the codec ID associated with the current formatIteratorP entry is stored. Pass NULL to ignore this value for each codec.
Return values:
Err errNone or kCodecErrBadParam

Err CodecMgrGetMaxDestBufferSize ( UInt16  refNum,
PalmCodecSession  session,
void *  srcBufferP,
UInt32  srcBufferSize,
UInt32 *  destBufferSizeP 
)

Returns the output buffer size required given an input buffer. This function is not required, but rather is provided to try to help the caller allocate the appropriate amount of memory for a call to CodecEncodeDecode that takes the same parameters. It is recommended that you always return a number equal to or larger then the buffer that will be required to hold the output of the CodecEncodeDecode call.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
session,: IN: Codec session reference received from CodecCreateSession.
srcBufferP,: IN: Input buffer.
srcBufferSize,: IN: Size of the input buffer in bytes.
destBufferSizeP,: OUT: Receives that maximum buffer size.
Return values:
Err errNone if no error, kCodecMgrLibNotSupported if no implemented.

Err CodecMgrGetSessionInfo ( UInt16  refNum,
PalmCodecSession  session,
PalmCodecFormat *  inputFormatP,
PalmCodecFormat *  outputFormatP,
UInt32 *  creatorIDP,
UInt32 *  codecIDP 
)

Get information about a session.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
session,: IN: Session to reset.
inputFormatP,: OUT: Receives the input format entry specified with formatIteratorP.
outputFormatP,: OUT: Receives the output format entry specified with formatIteratorP.
creatorIDP,: OUT: Pointer to the location where the creator ID of the session is returned.
codecIDP,: OUT: Pointer to the location where the codec ID of the session is returned.
Return values:
Err errNone if no error.

Boolean CodecMgrIsFormatSupported ( UInt16  refNum,
PalmCodecFormat  inputFormat,
PalmCodecFormat  outputFormat,
UInt32  creatorID,
UInt32  codecID 
)

Checks whether an input and output format pair is supported by any codec or by a particular codec.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
inputFormat,: IN: Input format for this session.
outputFormat,: IN: Output format for this session.
creatorID,: IN: Creator ID of the codec checked. Pass palmCodecNullID to ignore this parameter and check whether any available codec supports the given input and output format pair.
codecID,: IN: Codec ID of the codec checked. Pass palmCodecNullID to ignore this parameter and check whether any available codec supports the given input and output format pair.
Return values:
Boolean true if the format is supported by a codec or the specified codec, false if the format pair is not supported by a codec or the specified codec.

Err CodecMgrLibAPIVersion ( UInt16  refNum,
UInt32  codecMgrAPIVersion,
UInt32 *  codecMgrLibAPIVersionP 
)

Return the version of the Codec Plugin Manager library API to which this Codec was written. The API version of the manager that is loading this plugin is passed in, so that the plugin can either handle older managers, or return kCodecMgrLibNotSupported.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
codecMgrAPIVersion,: IN: The largest version of the codec API supported
codecMgrLibAPIVersionP,: IN: Receives the API version to which this plugin was written. If the plugin supports multiple API versions, this should be set to the same version as codecMgrAPIVersion.
Return values:
Err errNone if no error, kCodecMgrLibNotSupported if the manager is too old to handle this plugin

Err CodecMgrOpen ( UInt16  refNum  ) 

Opens the Codec Plugin Manager library.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
Return values:
Err errNone if no error

Err CodecMgrResetSession ( UInt16  refNum,
PalmCodecSession  session 
)

Reset a session.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
session,: IN: Session to reset.
Return values:
Err errNone if no error.

Err CodecMgrSleep ( UInt16  refNum  ) 

Standard Sleep function.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
Return values:
Err errNone if no error

Err CodecMgrWake ( UInt16  refNum  ) 

Standard Wake function.

Parameters:
refNum,: IN: Reference number of the CodecPluginMgr library.
Return values:
Err errNone if no error

Top Palm Developer Network
© 2004-2008, Palm, Inc. All rights reserved.
Generated on Fri Jun 13 10:07:49 2008 for Palm API Guide