workbench/libs/realtime/createplayera.c

   1 /*
   2     Copyright © 1995-2004, The AROS Development Team. All rights reserved.
   3     $Id$
   4 */
   5 # define  DEBUG 1
   6 # include <aros/debug.h>
   7
   8 #include <proto/exec.h>
   9 #include <proto/realtime.h>
  10 #include <proto/utility.h>
  11 #include <exec/memory.h>
  12 #include <utility/tagitem.h>
  13 #include "realtime_intern.h"
  14
  15 struct Conductor *createConductor(BOOL private, LONG *error,STRPTR name,
  16                                   struct Library *RealTimeBase);
  17
  18 /*****************************************************************************
  19
  20     NAME */
  21 #include <libraries/realtime.h>
  22
  23     AROS_LH1(struct Player *, CreatePlayerA,
  24
  25 /*  SYNOPSIS */
  26
  27         AROS_LHA(struct TagItem *, tagList, A0),
  28
  29 /*  LOCATION */
  30
  31         struct Library *, RealTimeBase, 7, RealTime)
  32
  33 /*  FUNCTION
  34
  35     Create a player.
  36
  37     INPUTS
  38
  39     tagList  --  pointer to an array of tags describing the player's
  40                  attributes or NULL.
  41
  42     TAGS
  43
  44     PLAYER_Name (STRPTR)         --  The name of the player; default is no
  45                                      name.
  46
  47     PLAYER_Hook (struct Hook *)  --  Function to call every time the time
  48                                      changes; default is none. The hook is
  49                                      called with
  50
  51                                      a0 -- address of Hook structure
  52                                      a1 -- message (see <libraries/realtime.h>)
  53                                      a2 -- address of Player structure
  54
  55                                      Be aware of that the function is not
  56                                      necessarily called TICK_FREQ times per
  57                                      second: this is the upper limit of times
  58                                      it may be called.
  59
  60     PLAYER_Priority (BYTE)       --  The priority of the player; default is 0.
  61
  62     PLAYER_Conductor (STRPTR)    --  The name of the conductor to link the
  63                                      player to. If the conductor doesn't exist,
  64                                      it's created automatically. Passing ~0
  65                                      creates a private conductor.
  66
  67     PLAYER_Ready (BOOL)          --  Set / clear the ready flag; default is
  68                                      TRUE.
  69
  70     PLAYER_AlarmTime (LONG)      --  Set player's alarm time; implies setting
  71                                      the PLAYERF_ALARMSET flag.
  72
  73     PLAYER_Alarm (BOOL)          --  Set / clear the PLAYERF_ALARMSET flag;
  74                                      default is FALSE.
  75
  76     PLAYER_AlarmSigTask (struct Task *)
  77                                  --  The task to signal when the alarm goes
  78                                      off; default is no task. If no task is
  79                                      specified PLAYERF_ALARMSET is turned
  80                                      off.
  81
  82     PLAYER_AlarmSigBit (BYTE)    --  Signal bit to use for the alarm or -1
  83                                      to disable signalling; default is -1.
  84
  85     PLAYER_Quiet (BOOL)          --  Specify whether this player should be
  86                                      ignored or not; default is FALSE.
  87                                      Generally only used by external sync
  88                                      applications.
  89
  90     PLAYER_UserData (VOID *)     --  Set pointer to user specific data;
  91                                      default is NULL.
  92
  93     PLAYER_ID (UWORD)            --  Set the player's ID; default is 0.
  94
  95     PLAYER_Conducted (BOOL)      --  Set / clear the PLAYERF_CONDUCTED flag;
  96                                      default is FALSE.
  97
  98     PLAYER_ExtSync (BOOL)        --  If TRUE, this player attempts to become
  99                                      the external sync source.
 100
 101     PLAYER_ErrorCode (LONG *)    --  Optional pointer to a LONG that will
 102                                      contain an error code if the function
 103                                      fails. Possible error values are:
 104
 105                                      RTE_NOMEMORY  --  memory allocation failed
 106                                      RTE_NOTIMER   --  timer allocation failed
 107
 108     RESULT
 109
 110     A pointer to a player structure or NULL if failure. In case of a failure
 111     additional information may be retreived from the LONG variable pointed
 112     to by PLAYER_ErrorCode if you have specified that tag.
 113
 114     NOTES
 115
 116     EXAMPLE
 117
 118     BUGS
 119
 120     SEE ALSO
 121
 122     DeletePlayer(), GetPlayerAttrsA(), SetPlayerAttrsA()
 123
 124     INTERNALS
 125
 126 ******************************************************************************/
 127
 128 {
 129     AROS_LIBFUNC_INIT
 130
 131     struct TagItem *tag, *tl = tagList;
 132     struct Player  *player = AllocMem(sizeof(struct Player),
 133                                       MEMF_PUBLIC | MEMF_CLEAR);
 134     LONG           *error;
 135
 136     D(bug("Entering CreatePlayerA()\n"));
 137
 138     error = (LONG *) GetTagData(PLAYER_ErrorCode, (IPTR) NULL, tl);
 139
 140     if (player == NULL)
 141     {
 142         if (error != NULL)
 143         {
 144             *error = RTE_NOMEMORY;
 145         }
 146
 147         return NULL;
 148     }
 149
 150     /* Set default values */
 151     player->pl_Reserved0 = -1;            /* AlarmSigBit */
 152     player->pl_Flags |= PLAYERF_READY;
 153
 154     while((tag = NextTagItem(&tl)) != NULL)
 155     {
 156         switch (tag->ti_Tag)
 157         {
 158         case PLAYER_Conductor:
 159
 160             D(bug("Found PLAYER_Conductor tag\n"));
 161
 162             if ((IPTR)tag->ti_Data == -1)
 163             {
 164                 player->pl_Source = createConductor(TRUE, error,
 165                                                     (STRPTR)tag->ti_Data,
 166                                                     RealTimeBase);
 167             }
 168             else
 169             {
 170                 struct Conductor *cd = FindConductor((STRPTR)tag->ti_Data);
 171
 172                 if (cd == NULL)
 173                 {
 174                     D(bug("Trying to create a public conductor.\n"));
 175                     player->pl_Source = createConductor(FALSE, error,
 176                                                         (STRPTR)tag->ti_Data,
 177                                                         RealTimeBase);
 178                 }
 179                 else
 180                 {
 181                     player->pl_Source = cd;
 182                 }
 183             }
 184
 185             if (player->pl_Source != NULL)
 186             {
 187                 APTR lock;
 188
 189                 lock = LockRealTime(RT_CONDUCTORS);
 190
 191                 /* Enqueue the player to the conductor list */
 192                 Enqueue((struct List *)&player->pl_Source->cdt_Players,
 193                         (struct Node *)player);
 194
 195                 UnlockRealTime(lock);
 196             }
 197
 198             break;
 199         }
 200
 201         /* The rest of the tags are taken care of in SetPlayerAttrsA() */
 202     }
 203
 204     D(bug("Calling SetPlayerAttrsA()\n"));
 205
 206     if (SetPlayerAttrsA(player, tagList))
 207     {
 208         return player;
 209     }
 210     else
 211     {
 212         return NULL;
 213     }
 214
 215     AROS_LIBFUNC_EXIT
 216 } /* CreatePlayerA */
 217
 218
 219 struct Conductor *createConductor(BOOL private, LONG *error, STRPTR name,
 220                                   struct Library *RealTimeBase)
 221 {
 222     struct Conductor *cd = AllocMem(sizeof(struct Conductor),
 223                                     MEMF_PUBLIC | MEMF_CLEAR);
 224
 225     if (cd == NULL)
 226     {
 227         if (error != NULL)
 228         {
 229             *error = RTE_NOMEMORY;
 230         }
 231
 232         return NULL;
 233     }
 234
 235     cd->cdt_Link.ln_Name = name;
 236
 237     NEWLIST(&cd->cdt_Players);
 238     InitSemaphore(&cd->cdt_Lock);
 239
 240     /* Initialize conductor clock */
 241     cd->cdt_ClockTime = GPB(RealTimeBase)->rtb_Time;
 242     cd->cdt_StartTime = GPB(RealTimeBase)->rtb_Time;
 243
 244     /* Conductors are created in 'stopped' mode. To make the clock start
 245        running, call SetConductorState(player, CONDSTATE_RUNNING, _); */
 246     cd->cdt_State = CONDSTATE_STOPPED;
 247
 248     if (private)
 249     {
 250         cd->cdt_Flags |= CONDUCTF_PRIVATE;
 251     }
 252
 253     {
 254         /* Add the conductor to the realtime library conductor list */
 255         APTR lock;
 256
 257         lock = LockRealTime(RT_CONDUCTORS);
 258
 259         AddTail((struct List *)&GPB(RealTimeBase)->rtb_ConductorList,
 260                 (struct Node *)cd);
 261
 262         UnlockRealTime(lock);
 263     }
 264
 265     return cd;
 266 }