/****************************************************************************** * Copyright (c) 2004 palmOne, Inc. or its subsidiaries. * All rights reserved. *****************************************************************************/ /** * @ingroup Codec */ /** * @file palmOneCodecPluginMgr.h * @version 3.0 * * @brief 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. * * A typical application would use the library the following way: * - Check is an input/output format pair is supported [optional] * - Create a CodecSession with parameters that match the formats * - Call EncodeDecode() * - ... * - Delete the session. * */ #ifndef _PALMONECODECPLUGINMGR_H_ #define _PALMONECODECPLUGINMGR_H_ #include #include #include #include #include /*********************************************************************** * API Prototypes ***********************************************************************/ #ifdef __cplusplus extern "C" { #endif /** * Opens the Codec Plugin Manager library. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @retval Err errNone if no error */ Err CodecMgrOpen(UInt16 refNum) SYS_TRAP(sysLibTrapOpen); /** * Closes the Codec Plugin Manager library. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @retval Err The library is closed and errNone is returned. If another application is still using the * library, a kCodecMgrLibStillOpen error is returned. */ Err CodecMgrClose(UInt16 refNum) SYS_TRAP(sysLibTrapClose); /** * Standard Sleep function. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @retval Err errNone if no error */ Err CodecMgrSleep(UInt16 refNum) SYS_TRAP(sysLibTrapSleep); /** * Standard Wake function. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @retval Err errNone if no error */ Err CodecMgrWake(UInt16 refNum) SYS_TRAP(sysLibTrapWake); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param codecMgrAPIVersion: IN: The largest version of the codec API supported * @param 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. * @retval Err errNone if no error, kCodecMgrLibNotSupported if the manager * is too old to handle this plugin */ Err CodecMgrLibAPIVersion(UInt16 refNum, UInt32 codecMgrAPIVersion, UInt32 *codecMgrLibAPIVersionP) SYS_TRAP(kCodecMgrLibTrapLibAPIVersion); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param inputFormat: IN: Input format for this session. * @param inputParamP: IN: Parameter associated with the input format. NULL if not needed. * @param outputFormat: IN: Output format for this session. * @param outputParamP: IN: Parameter associated with the output format. NULL if not needed. * @param sessionP OUT: Receives the reference to the newly created session. This reference is passed into all future calls for this session. * * @retval Err errNone if no error. */ Err CodecMgrCreateSession(UInt16 refNum, PalmCodecFormat inputFormat, void *inputParamP, PalmCodecFormat outputFormat, void *outputParamP, PalmCodecSession *sessionP) SYS_TRAP(kCodecMgrLibTrapCreateSession); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param inputFormat: IN: Input format for this session. * @param inputParamP: IN: Parameter associated with the input format. NULL if not needed. * @param outputFormat: IN: Output format for this session. * @param outputParamP: IN: Parameter associated with the output format. NULL if not needed. * @param creatorID: IN: Creator ID of the module containing the codec. * @param codecID: IN: Codec ID for a specific codec. * @param sessionP: OUT: Receives the reference to the newly created session. This reference is passed into all future calls for this session. * * @return errNone if no error. */ Err CodecMgrCreateSessionByID(UInt16 refNum, PalmCodecFormat inputFormat, void *inputParamP, PalmCodecFormat outputFormat, void *outputParamP, UInt32 creatorID, UInt32 codecID, PalmCodecSession *sessionP) SYS_TRAP(kCodecMgrLibTrapCreateSessionByID); /** * Delete a session. * This function has to delete any allocated memory and set the * session reference to NULL. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param sessionP: IN: Pointer to the Codec session reference received from CodecCreateSession. * @retval Err errNone if no error. */ Err CodecMgrDeleteSession(UInt16 refNum, PalmCodecSession *sessionP) SYS_TRAP(kCodecMgrLibTrapDeleteSession); /** * Reset a session. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param session: IN: Session to reset. * @retval Err errNone if no error. */ Err CodecMgrResetSession(UInt16 refNum, PalmCodecSession session) SYS_TRAP(kCodecMgrLibTrapResetSession); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param session: IN: Codec session reference received from CodecCreateSession. * @param srcBufferP: IN: Input buffer. * @param srcBufferSize: IN: Size of the input buffer in bytes. * @param destBufferSizeP: OUT: Receives that maximum buffer size. * * @retval Err errNone if no error, kCodecMgrLibNotSupported if no implemented. */ Err CodecMgrGetMaxDestBufferSize(UInt16 refNum, PalmCodecSession session, void *srcBufferP, UInt32 srcBufferSize, UInt32 *destBufferSizeP) SYS_TRAP(kCodecMgrLibTrapGetMaxDestBufferSize); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param session: IN: Codec session reference received from CodecCreateSession. * @param srcBufferP: IN: The source buffer to be processed. * @param 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. * @param destBufferP: OUT: The destination buffer which receives the encoded/decoded data. * @param destBufferSizeP: IN,OUT: On input, the size of destBufferP in bytes, on output the number of bytes of data written. * * @retval Err errNone if no error */ Err CodecMgrEncodeDecode(UInt16 refNum, PalmCodecSession session, void *srcBufferP, UInt32 *srcBufferSizeP, void *destBufferP, UInt32 *destBufferSizeP) SYS_TRAP(kCodecMgrLibTrapEncodeDecode); /** * 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. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param session: IN: Codec session reference received from CodecCreateSession. * @param apiCreator: IN: Registered creator code. * @param apiSelector: IN: Custom operation to perform. * @param valueP: IN: Buffer containing data specific to the operation. * @param valueLenP: IN,OUT: Size of the valueP buffer on entry, size of data written to * valueP on exit. If NULL, valueP is ignored. * @retval Err errNone if no error, kCodecMgrLibNotSupported if not supported. */ Err CodecMgrCustomControl(UInt16 refNum, PalmCodecSession session, UInt32 apiCreator, UInt32 apiSelector, void *valueP, UInt32 *valueLenP) SYS_TRAP(kCodecMgrLibTrapCustomControl); /** * 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 * } * } * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param 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. * @param inputFormatP: IN: Receives the input format entry specified with formatIteratorP. * @param outputFormatP: IN: Receives the output format entry specified with formatIteratorP. * @param 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. * @param 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. * * @retval Err errNone or kCodecErrBadParam */ Err CodecMgrEnumerateFormats(UInt16 refNum, UInt32 *formatIteratorP, PalmCodecFormat *inputFormatP, PalmCodecFormat *outputFormatP, UInt32 *creatorIDP, UInt32 *codecIDP) SYS_TRAP(kCodecMgrLibTrapEnumerateFormats); /** * Checks whether an input and output format pair is supported by any codec or by * a particular codec. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param inputFormat: IN: Input format for this session. * @param outputFormat: IN: Output format for this session. * @param 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. * @param 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. * * @retval 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. */ Boolean CodecMgrIsFormatSupported(UInt16 refNum, PalmCodecFormat inputFormat, PalmCodecFormat outputFormat, UInt32 creatorID, UInt32 codecID) SYS_TRAP(kCodecMgrLibTrapIsFormatSupported); /** * Get information about a session. * * @param refNum: IN: Reference number of the CodecPluginMgr library. * @param session: IN: Session to reset. * @param inputFormatP: OUT: Receives the input format entry specified with formatIteratorP. * @param outputFormatP: OUT: Receives the output format entry specified with formatIteratorP. * @param creatorIDP: OUT: Pointer to the location where the creator ID of the session is returned. * @param codecIDP: OUT: Pointer to the location where the codec ID of the session is returned. * * @retval Err errNone if no error. */ Err CodecMgrGetSessionInfo(UInt16 refNum, PalmCodecSession session, PalmCodecFormat *inputFormatP, PalmCodecFormat *outputFormatP, UInt32 *creatorIDP, UInt32 *codecIDP) SYS_TRAP(kCodecMgrLibTrapGetSessionInfo); #ifdef __cplusplus } #endif #endif // _PALMCODECPLUGINMGR_H_