API Guide Home (Online version only) |

# PalmAudioPlayback.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 Sound
    00007  *
    00008  */
    00009
    00010 /**
    00011  *
    00012  * @file    PalmAudioPlayback.h
    00013  *
    00014  * @brief   Public 68K include file that supports the stopping of audio
    00015  *          playback on Treo 600 and Treo 650 smartphones.
    00016  *
    00017  * This header file and associated header files support the specific sound
    00018  * functionality of the Treo smartphones. You should use the Palm OS Sound
    00019  * Manager APIs for most of your work.
    00020  *
    00021  * Notes:
    00022  *   This header contains a notification to call for stopping any existing
    00023  *   background audio playback.
    00024  *
    00025  *   Any application ( usually video capture ) that needs to stop and eventually resume
    00026  *   audio playback should use this header. Stopping or resuming playback is done by
    00027  *   throwing a notification.
    00028  *
    00029  *   Audio playback applications should register for this notification and stop playback
    00030  *   when they get the stop action code. They can optionally resume action when they get
    00031  *   a notification with a resume action code. However resume is not
    00032  *   a mandatory feature neither for the calling application nor for the audio application.
    00033  *   In other words, the audio application may never get a resume after a stop action code.
    00034  *
    00035  *   Usage for any application requesting stop of audio playback:
    00036  *
    00037  *   PalmAudioPlaybackRequestStop('cccc'); // to stop background playback
    00038  *   PalmAudioPlaybackRequestResume('cccc'); // to resume background playback
    00039  *
    00040  *   The calling application should always load this library with
    00041  *   SysLibLoad() before use, even if it is already open by another
    00042  *   application(ie, SysLibFind() returns a valid refnum). When
    00043  *   the application is done with the library, it should be
    00044  *   unloaded with SysLibRemove(). We do this because there is
    00045  *   no good way to synchronize loading and unloading of libraries
    00046  *   among multiple applications. It also greatly simplifies internal
    00047  *   synchronization.
    00048  */
    00049
    00050
    00051 #ifndef __PalmAudioPlayback_H__
    00052 #define __PalmAudioPlayback_H__
    00053
    00054 /***********************************************************************
    00055  * Palm OS common definitions
    00056  ***********************************************************************/
    00057 #include <PalmTypes.h>
    00058 #include <SystemMgr.h>
    00059 #include <NotifyMgr.h>
    00060 #include <MemoryMgr.h>
    00061
    00062 /**
    00063  * @name PalmAudioPlayback information and notification
    00064  *
    00065  */
    00066
    00067 /*@{*/
    00068 #define kPalmAudioPlaybackNotify1 sysMakeROMVersion(1, 0, 0, sysROMStageRelease, 0)
    00069
    00070 /** Version of the PalmAudioPlayback library. */
    00071 #define kPalmAudioPlaybackNotifyVersion kPalmAudioPlaybackNotify1
    00072
    00073 /** PalmAudioPlayback creator ID. */
    00074 #define kPalmAudioPlaybackCreator 'apbP'
    00075
    00076 /** Playback notification event ID.
    00077  *
    00078  *  Applications playing audio should register for this notification
    00079  *  and stop or optionally resume playback depending on the action code the application receives.
    00080  */
    00081 #define kPalmAudioPlaybackNotifyEvent kPalmAudioPlaybackCreator
    00082 /*@}*/
    00083
    00084 /** Holds action codes for the kPalmAudioPlaybackNotifyEvent broadcast. */
    00085 typedef UInt16 PalmAudioPlaybackActionCodeType;
    00086
    00087 /**
    00088  * @name Audio playback action codes
    00089  *
    00090  */
    00091
    00092 /*@{*/
    00093 /** Playback stop action code. */
    00094 #define kPalmAudioPlaybackActionCodeRequestStop     ((PalmAudioPlaybackActionCodeType)1)
    00095
    00096 /** Playback resume action code. */
    00097 #define kPalmAudioPlaybackActionCodeRequestResume    ((PalmAudioPlaybackActionCodeType)2)
    00098 /*@}*/
    00099
    00100 /** Audio playback notification structure.
    00101  *
    00102  *  Structure that is sent as part of notifyDetailsP when a kPalmAudioPlaybackNotifyEvent
    00103  *  is thrown.
    00104  */
    00105 typedef struct PalmAudioPlaybackNotifyEventTypeTag
    00106 {
    00107     UInt32 version;                             /**< Version. */
    00108     PalmAudioPlaybackActionCodeType actionCode; /**< Action code. */
    00109     void* dataP;                                /**< Data for action code, currently NULL. */
    00110 } PalmAudioPlaybackNotifyEventType;
    00111
    00112 /**
    00113  * @name Audio playback helper macros
    00114  *
    00115  */
    00116 /*@{*/
    00117 #define PalmAudioPlaybackRequestStop(creator) \
    00118     { \
    00119         PalmAudioPlaybackNotifyEventType request = \
    00120         { \
    00121             kPalmAudioPlaybackNotifyVersion, \
    00122             kPalmAudioPlaybackActionCodeRequestStop, \
    00123             0 \
    00124         }; \
    00125         PalmAudioPlaybackSendRequest(&request, creator); \
    00126     }
    00127     /**<Request to stop playback. Any application that needs to request a stop of
    00128         audio playback should use this macro. "creator" is the creator id of the calling
    00129         function. */
    00130
    00131 #define PalmAudioPlaybackRequestResume(creator) \
    00132     { \
    00133         PalmAudioPlaybackNotifyEventType request = \
    00134         { \
    00135             kPalmAudioPlaybackNotifyVersion, \
    00136             kPalmAudioPlaybackActionCodeRequestResume, \
    00137             0 \
    00138         }; \
    00139         PalmAudioPlaybackSendRequest(&request, creator); \
    00140     }
    00141     /**<Request to resume playback. Any application that needs to request that
    00142         audio playback be resumed should use this macro. "creator" is the creator id of the calling
    00143         function. */
    00144
    00145 #define PalmAudioPlaybackSendRequest(requestP, creator) \
    00146     { \
    00147         SysNotifyParamType      notify; \
    00148         MemSet(&notify, sizeof(SysNotifyParamType), 0); \
    00149         notify.notifyType       = kPalmAudioPlaybackNotifyEvent; \
    00150         notify.broadcaster      = creator; \
    00151         notify.notifyDetailsP   = (void*)requestP; \
    00152         SysNotifyBroadcast(&notify); \
    00153     }
    00154     /**<Actual broadcast of kPalmAudioPlaybackNotifyEvent notification. Used by Stop and
    00155         Resume macros. */
    00156 /*@}*/
    00157
    00158 #endif // __PalmAudioPlayback_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