API Guide Home (Online version only) |

# palmOneCodecPluginMgr.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup Codec
    00007  */
    00008
    00009 /**
    00010  * @file    palmOneCodecPluginMgr.h
    00011  * @version 3.0
    00012  *
    00013  * @brief   The Codec Plugin Manager is used to unify all different type of
    00014  *          codecs that are available for PalmOne devices and provide a generic
    00015  *          API for developers to access these codecs.
    00016  *
    00017  * A typical application would use the library the following way:
    00018  * - Check is an input/output format pair is supported [optional]
    00019  * - Create a CodecSession with parameters that match the formats
    00020  * - Call EncodeDecode()
    00021  * - ...
    00022  * - Delete the session.
    00023  *
    00024  */
    00025
    00026 #ifndef _PALMONECODECPLUGINMGR_H_
    00027 #define _PALMONECODECPLUGINMGR_H_
    00028
    00029 #include <PalmTypes.h>
    00030 #include <ErrorBase.h>
    00031 #include <SystemMgr.h>
    00032 #include <LibTraps.h>
    00033 #include <palmOneCodecPluginMgrCommon.h>
    00034
    00035 /***********************************************************************
    00036  * API Prototypes
    00037  ***********************************************************************/
    00038
    00039 #ifdef __cplusplus
    00040 extern "C" {
    00041 #endif
    00042
    00043 /**
    00044  * Opens the Codec Plugin Manager library.
    00045  *
    00046  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00047  * @retval Err errNone if no error
    00048  */
    00049 Err CodecMgrOpen(UInt16 refNum)
    00050         SYS_TRAP(sysLibTrapOpen);
    00051 /**
    00052  * Closes the Codec Plugin Manager library.
    00053  *
    00054  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00055  * @retval Err The library is closed and errNone is returned. If another application is still using the
    00056  *             library, a kCodecMgrLibStillOpen error is returned.
    00057  */
    00058 Err CodecMgrClose(UInt16 refNum)
    00059         SYS_TRAP(sysLibTrapClose);
    00060
    00061 /**
    00062  * Standard Sleep function.
    00063  *
    00064  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00065  * @retval Err errNone if no error
    00066  */
    00067 Err CodecMgrSleep(UInt16 refNum)
    00068         SYS_TRAP(sysLibTrapSleep);
    00069
    00070
    00071 /**
    00072  * Standard Wake function.
    00073  *
    00074  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00075  * @retval Err errNone if no error
    00076  */
    00077 Err CodecMgrWake(UInt16 refNum)
    00078         SYS_TRAP(sysLibTrapWake);
    00079
    00080 /**
    00081  * Return the version of the Codec Plugin Manager library API to which
    00082  * this Codec was written. The API version of the manager that is loading
    00083  * this plugin is passed in, so that the plugin can either handle older
    00084  * managers, or return kCodecMgrLibNotSupported.
    00085  *
    00086  * @param refNum:                   IN: Reference number of the CodecPluginMgr library.
    00087  * @param codecMgrAPIVersion:       IN: The largest version of the codec API supported
    00088  * @param codecMgrLibAPIVersionP:   IN: Receives the API version to which this plugin was written.
    00089  *                                      If the plugin supports multiple API versions, this should
    00090  *                                      be set to the same version as codecMgrAPIVersion.
    00091  * @retval Err errNone if no error, kCodecMgrLibNotSupported if the manager
    00092  *             is too old to handle this plugin
    00093  */
    00094 Err CodecMgrLibAPIVersion(UInt16 refNum, UInt32 codecMgrAPIVersion, UInt32 *codecMgrLibAPIVersionP)
    00095         SYS_TRAP(kCodecMgrLibTrapLibAPIVersion);
    00096
    00097 /**
    00098  * Create a Codec Session.
    00099  * A session is Codec dependent, which means it is up to a Codec to define
    00100  * the structure (if any) pointed by the Session.
    00101  * This function is called by the CodecPluginMgr. At this stage, the CPM
    00102  * has already selected a known format pair from its codec list.
    00103  * The input and output parameters have to match the format they represent.
    00104  * E.g. palmCodecImageJPEG as input uses PalmJPEGEncodeType
    00105  *      palmCodecImageJPEG as output uses PalmJPEGDecodeType etc.
    00106  *
    00107  * @param refNum:       IN: Reference number of the CodecPluginMgr library.
    00108  * @param inputFormat:  IN: Input format for this session.
    00109  * @param inputParamP:  IN: Parameter associated with the input format. NULL if not needed.
    00110  * @param outputFormat: IN: Output format for this session.
    00111  * @param outputParamP: IN: Parameter associated with the output format. NULL if not needed.
    00112  * @param sessionP      OUT: Receives the reference to the newly created session.  This reference is passed into all future calls for this session.
    00113  *
    00114  * @retval Err errNone if no error.
    00115  */
    00116 Err CodecMgrCreateSession(UInt16 refNum, PalmCodecFormat inputFormat, void *inputParamP, PalmCodecFormat outputFormat, void *outputParamP, PalmCodecSession *sessionP)
    00117         SYS_TRAP(kCodecMgrLibTrapCreateSession);
    00118
    00119
    00120 /**
    00121  * Create a Codec Session using Creator and Codec  ID.
    00122  * A session is Codec dependent, which means it is
    00123  * up to a Codec to define the structure (if any) pointed by the Session.
    00124  * This function is called by the CodecPluginMgr. At this stage, the CPM
    00125  * has already selected a known format pair from its codec list.
    00126  * The input and output parameters have to match the format they represent.
    00127  * E.g. palmCodecImageJPEG as input uses PalmJPEGEncodeType
    00128  *      palmCodecImageJPEG as output uses PalmJPEGDecodeType etc.
    00129  *
    00130  * This function is used to create a session when a multiple codecs
    00131  * using the same input and output format are available.
    00132  *
    00133  * @param refNum:       IN: Reference number of the CodecPluginMgr library.
    00134  * @param inputFormat:  IN: Input format for this session.
    00135  * @param inputParamP:  IN: Parameter associated with the input format. NULL if not needed.
    00136  * @param outputFormat: IN: Output format for this session.
    00137  * @param outputParamP: IN: Parameter associated with the output format. NULL if not needed.
    00138  * @param creatorID:    IN: Creator ID of the module containing the codec.
    00139  * @param codecID:      IN: Codec ID for a specific codec.
    00140  * @param sessionP:     OUT: Receives the reference to the newly created session.  This reference is passed into all future calls for this session.
    00141  *
    00142  * @return  errNone if no error.
    00143  */
    00144 Err CodecMgrCreateSessionByID(UInt16 refNum, PalmCodecFormat inputFormat, void *inputParamP, PalmCodecFormat outputFormat, void *outputParamP, UInt32 creatorID, UInt32 codecID, PalmCodecSession *sessionP)
    00145         SYS_TRAP(kCodecMgrLibTrapCreateSessionByID);
    00146
    00147
    00148 /**
    00149  * Delete a session.
    00150  * This function has to delete any allocated memory and set the
    00151  * session reference to NULL.
    00152  *
    00153  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00154  * @param sessionP: IN: Pointer to the Codec session reference received from CodecCreateSession.
    00155  * @retval Err errNone if no error.
    00156  */
    00157 Err CodecMgrDeleteSession(UInt16 refNum, PalmCodecSession *sessionP)
    00158         SYS_TRAP(kCodecMgrLibTrapDeleteSession);
    00159
    00160 /**
    00161  * Reset a session.
    00162  *
    00163  * @param refNum:   IN: Reference number of the CodecPluginMgr library.
    00164  * @param session:  IN: Session to reset.
    00165  * @retval Err errNone if no error.
    00166  */
    00167 Err CodecMgrResetSession(UInt16 refNum, PalmCodecSession session)
    00168         SYS_TRAP(kCodecMgrLibTrapResetSession);
    00169
    00170 /**
    00171  * Returns the output buffer size required given an input buffer.
    00172  * This function is not required, but rather is provided to try to help the caller
    00173  * allocate the appropriate amount of memory for a call to CodecEncodeDecode
    00174  * that takes the same parameters.  It is recommended that you always return
    00175  * a number equal to or larger then the buffer that will be required to hold
    00176  * the output of the CodecEncodeDecode call.
    00177  *
    00178  * @param refNum:           IN: Reference number of the CodecPluginMgr library.
    00179  * @param session:          IN: Codec session reference received from CodecCreateSession.
    00180  * @param srcBufferP:       IN: Input buffer.
    00181  * @param srcBufferSize:    IN: Size of the input buffer in bytes.
    00182  * @param destBufferSizeP:  OUT: Receives that maximum buffer size.
    00183  *
    00184  * @retval Err errNone if no error, kCodecMgrLibNotSupported if no implemented.
    00185  */
    00186 Err CodecMgrGetMaxDestBufferSize(UInt16 refNum, PalmCodecSession session, void *srcBufferP, UInt32 srcBufferSize, UInt32 *destBufferSizeP)
    00187         SYS_TRAP(kCodecMgrLibTrapGetMaxDestBufferSize);
    00188 /**
    00189  * Encode or decode a block of data.
    00190  * The format of the source and destination buffers are set in a
    00191  * preceding call to CodecCreateSession and possibly calls to CodecCustomControl.
    00192  * Is is legal for this function to not encode/decode the whole source buffer.  For
    00193  * example, if the source buffer contains a non-round number of encoded blocks, and the
    00194  * encoding format requires whole blocks, this call should encode/decode the even
    00195  * number of blocks, and set srcBufferP appropriately to indicate how much of the
    00196  * source data was actually encoded.  The caller should then pass the un-encoded piece of
    00197  * the last chunk in on the next call to this function with the next chunk of data
    00198  * appended to the end of it.
    00199  *
    00200  * @param refNum:           IN: Reference number of the CodecPluginMgr library.
    00201  * @param session:          IN: Codec session reference received from CodecCreateSession.
    00202  * @param srcBufferP:       IN: The source buffer to be processed.
    00203  * @param srcBufferSizeP:   IN,OUT: On input, the size of srcBufferP in bytes.  If the whole
    00204  *                                  buffer is not processed, on output srcBufferP is set to the amount of
    00205  *                                  source data that was processed.
    00206  * @param destBufferP:      OUT: The destination buffer which receives the encoded/decoded data.
    00207  * @param destBufferSizeP:  IN,OUT: On input, the size of destBufferP in bytes, on output the number of bytes of data written.
    00208  *
    00209  * @retval Err errNone if no error
    00210  */
    00211 Err CodecMgrEncodeDecode(UInt16 refNum, PalmCodecSession session, void *srcBufferP, UInt32 *srcBufferSizeP, void *destBufferP, UInt32 *destBufferSizeP)
    00212         SYS_TRAP(kCodecMgrLibTrapEncodeDecode);
    00213
    00214 /**
    00215  * Handle a custom call.
    00216  *
    00217  * The codec identifies the call and its API by a registered creator code and a selector.
    00218  * This allows codec developers to extend the API by defining selectors for their
    00219  * creator code. It also allows driver developers to support selectors (and custom calls)
    00220  * defined by other driver developers.
    00221  *
    00222  * @param refNum:       IN: Reference number of the CodecPluginMgr library.
    00223  * @param session:      IN: Codec session reference received from CodecCreateSession.
    00224  * @param apiCreator:   IN: Registered creator code.
    00225  * @param apiSelector:  IN: Custom operation to perform.
    00226  * @param valueP:       IN: Buffer containing data specific to the operation.
    00227  * @param valueLenP:    IN,OUT: Size of the valueP buffer on entry, size of data written to
    00228  *                              valueP on exit. If NULL, valueP is ignored.
    00229  * @retval Err errNone if no error, kCodecMgrLibNotSupported if not supported.
    00230  */
    00231 Err CodecMgrCustomControl(UInt16 refNum, PalmCodecSession session, UInt32 apiCreator, UInt32 apiSelector, void *valueP, UInt32 *valueLenP)
    00232         SYS_TRAP(kCodecMgrLibTrapCustomControl);
    00233
    00234 /**
    00235  * Enumerate all supported input and output format pairs.
    00236  * A pair describes what input format is expected and what output format
    00237  * will come out of the Codec. Codecs can accept multiple format pairs.
    00238  * For example, an MP3 Codec might be able to decode only MP3, MP2, and MP1.
    00239  * In this case, the pairs are:
    00240  *      [in: MP3    out: PCM    codecID: 0]
    00241  *      [in: MP2    out: PCM    codecID: 0]
    00242  *      [in: MP1    out: PCM    codecID: 0]
    00243  *
    00244  * The Codec ID is used if multiple codecs within the same PRC have the exact
    00245  * same input and output formats. For example, a DSP filter bank might specify
    00246  * PCM as both the input and output for every codec. Codec ID helps differentiate between
    00247  * these Codecs (Low-Pass, High-Pass, Band-Pass...).
    00248  * A Codec ID set to 0 (palmNULLCodecID) means that there is no need to look for
    00249  * a particular codec (for example, if there is only one codec in the PRC).
    00250  *
    00251  * Pass a formatIteratorP of palmCodecIteratorStart to get the first pair.
    00252  * formatIteratorP will be updated to the next item. When returning the last
    00253  * format pair, the formatIteratorP will be set to palmCodecIteratorStop.
    00254  *
    00255  * Sample:
    00256  *
    00257  * PalmCodecFormat inputFormat, outputFormat;
    00258  * UInt32 codecID;
    00259  * UInt32 formatIterator = palmCodecIteratorStart;
    00260  * while (formatIterator != palmCodecIteratorStop) {
    00261  *      if ((err = CodecEnumerateSupportedFormats(&formatIterator, &inputFormat, &outputFormat, &codecID)) != errNone) {
    00262  *              // Do something with the format pair
    00263  *      } else {
    00264  *              // handle error... possibly by breaking out of the loop
    00265  *      }
    00266  * }
    00267  *
    00268  * @param refNum:           IN: Reference number of the CodecPluginMgr library.
    00269  * @param formatIteratorP:  IN,OUT: Reference to the last entry enumerated
    00270  *                                  Pass palmCodecIteratorStart to get the first entry.
    00271  *                                  This is updated on return to reference the next entry
    00272  *                                  or set to palmCodecIteratorStop if last directory entry.
    00273  * @param inputFormatP:     IN: Receives the input format entry specified with formatIteratorP.
    00274  * @param outputFormatP:    IN: Receives the output format entry specified with formatIteratorP.
    00275  * @param creatorIDP:       IN: Pointer to the location where the creator ID associated with the current
    00276  *                              formatIteratorP entry is stored. Pass NULL to ignore this value for each codec.
    00277  * @param codecIDP:         IN: Pointer to the location where the codec ID associated with the current
    00278  *                              formatIteratorP entry is stored. Pass NULL to ignore this value for each codec.
    00279  *
    00280  * @retval Err errNone or kCodecErrBadParam
    00281  */
    00282 Err CodecMgrEnumerateFormats(UInt16 refNum, UInt32 *formatIteratorP, PalmCodecFormat *inputFormatP, PalmCodecFormat *outputFormatP, UInt32 *creatorIDP, UInt32 *codecIDP)
    00283         SYS_TRAP(kCodecMgrLibTrapEnumerateFormats);
    00284
    00285 /**
    00286  * Checks whether an input and output format pair is supported by any codec or by
    00287  * a particular codec.
    00288  *
    00289  * @param refNum:       IN: Reference number of the CodecPluginMgr library.
    00290  * @param inputFormat:  IN: Input format for this session.
    00291  * @param outputFormat: IN: Output format for this session.
    00292  * @param creatorID:    IN: Creator ID of the codec checked. Pass palmCodecNullID to ignore this parameter
    00293  *                          and check whether any available codec supports the given input and output
    00294  *                          format pair.
    00295  * @param codecID:      IN: Codec ID of the codec checked. Pass palmCodecNullID to ignore this parameter
    00296  *                          and check whether any available codec supports the given input and output
    00297  *                          format pair.
    00298  *
    00299  * @retval Boolean true if the format is supported by a codec or the specified codec, false if the format
    00300  *                 pair is not supported by a codec or the specified codec.
    00301  */
    00302 Boolean CodecMgrIsFormatSupported(UInt16 refNum, PalmCodecFormat inputFormat, PalmCodecFormat outputFormat, UInt32 creatorID, UInt32 codecID)
    00303         SYS_TRAP(kCodecMgrLibTrapIsFormatSupported);
    00304
    00305 /**
    00306  * Get information about a session.
    00307  *
    00308  * @param refNum:           IN: Reference number of the CodecPluginMgr library.
    00309  * @param session:          IN: Session to reset.
    00310  * @param inputFormatP:     OUT: Receives the input format entry specified with formatIteratorP.
    00311  * @param outputFormatP:    OUT: Receives the output format entry specified with formatIteratorP.
    00312  * @param creatorIDP:       OUT: Pointer to the location where the creator ID of the session is returned.
    00313  * @param codecIDP:         OUT: Pointer to the location where the codec ID of the session is returned.
    00314  *
    00315  * @retval Err errNone if no error.
    00316  */
    00317 Err CodecMgrGetSessionInfo(UInt16 refNum, PalmCodecSession session, PalmCodecFormat *inputFormatP, PalmCodecFormat *outputFormatP, UInt32 *creatorIDP, UInt32 *codecIDP)
    00318         SYS_TRAP(kCodecMgrLibTrapGetSessionInfo);
    00319
    00320
    00321
    00322 #ifdef __cplusplus
    00323 }
    00324 #endif
    00325
    00326 #endif  // _PALMCODECPLUGINMGR_H_

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