workbench/libs/realtime/createplayera.c

   1 /*
   2     Copyright © 1995-2016, The AROS Development Team. All rights reserved.
   3     $Id$
   4 */
   5 # define  DEBUG 0
   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 /*****************************************************************************
  16
  17     NAME */
  18 #include <libraries/realtime.h>
  19
  20     AROS_LH1(struct Player *, CreatePlayerA,
  21
  22 /*  SYNOPSIS */
  23
  24         AROS_LHA(struct TagItem *, tagList, A0),
  25
  26 /*  LOCATION */
  27
  28         struct Library *, RealTimeBase, 7, RealTime)
  29
  30 /*  FUNCTION
  31
  32     Create a player.
  33
  34     INPUTS
  35
  36     tagList  --  pointer to an array of tags describing the player's
  37                  attributes or NULL.
  38
  39     TAGS
  40
  41     PLAYER_Name (STRPTR)         --  The name of the player; default is no
  42                                      name.
  43
  44     PLAYER_Hook (struct Hook *)  --  Function to call every time the time
  45                                      changes; default is none. The hook is
  46                                      called with
  47
  48                                      a0 -- address of Hook structure
  49                                      a1 -- message (see <libraries/realtime.h>)
  50                                      a2 -- address of Player structure
  51
  52                                      Be aware of that the function is not
  53                                      necessarily called TICK_FREQ times per
  54                                      second: this is the upper limit of times
  55                                      it may be called.
  56
  57     PLAYER_Priority (BYTE)       --  The priority of the player; default is 0.
  58
  59     PLAYER_Conductor (STRPTR)    --  The name of the conductor to link the
  60                                      player to. If the conductor doesn't exist,
  61                                      it's created automatically. Passing ~0
  62                                      creates a private conductor.
  63
  64     PLAYER_Ready (BOOL)          --  Set / clear the ready flag; default is
  65                                      TRUE.
  66
  67     PLAYER_AlarmTime (LONG)      --  Set player's alarm time; implies setting
  68                                      the PLAYERF_ALARMSET flag.
  69
  70     PLAYER_Alarm (BOOL)          --  Set / clear the PLAYERF_ALARMSET flag;
  71                                      default is FALSE.
  72
  73     PLAYER_AlarmSigTask (struct Task *)
  74                                  --  The task to signal when the alarm goes
  75                                      off; default is no task. If no task is
  76                                      specified PLAYERF_ALARMSET is turned
  77                                      off.
  78
  79     PLAYER_AlarmSigBit (BYTE)    --  Signal bit to use for the alarm or -1
  80                                      to disable signalling; default is -1.
  81
  82     PLAYER_Quiet (BOOL)          --  Specify whether this player should be
  83                                      ignored or not; default is FALSE.
  84                                      Generally only used by external sync
  85                                      applications.
  86
  87     PLAYER_UserData (VOID *)     --  Set pointer to user specific data;
  88                                      default is NULL.
  89
  90     PLAYER_ID (UWORD)            --  Set the player's ID; default is 0.
  91
  92     PLAYER_Conducted (BOOL)      --  Set / clear the PLAYERF_CONDUCTED flag;
  93                                      default is FALSE.
  94
  95     PLAYER_ExtSync (BOOL)        --  If TRUE, this player attempts to become
  96                                      the external sync source.
  97
  98     PLAYER_ErrorCode (LONG *)    --  Optional pointer to a LONG that will
  99                                      contain an error code if the function
 100                                      fails. Possible error values are:
 101
 102                                      RTE_NOMEMORY  --  memory allocation failed
 103                                      RTE_NOTIMER   --  timer allocation failed
 104
 105     RESULT
 106
 107     A pointer to a player structure or NULL if failure. In case of a failure
 108     additional information may be retreived from the LONG variable pointed
 109     to by PLAYER_ErrorCode if you have specified that tag.
 110
 111     NOTES
 112
 113     EXAMPLE
 114
 115     BUGS
 116
 117     SEE ALSO
 118
 119     DeletePlayer(), GetPlayerAttrsA(), SetPlayerAttrsA()
 120
 121     INTERNALS
 122
 123 ******************************************************************************/
 124
 125 {
 126     AROS_LIBFUNC_INIT
 127
 128     struct Player  *player = AllocMem(sizeof(struct Player),
 129                                       MEMF_PUBLIC | MEMF_CLEAR);
 130     LONG           *error;
 131
 132     D(bug("Entering CreatePlayerA()\n"));
 133
 134     error = (LONG *) GetTagData(PLAYER_ErrorCode, (IPTR) NULL, tagList);
 135
 136     if (player == NULL)
 137     {
 138         if (error != NULL)
 139         {
 140             *error = RTE_NOMEMORY;
 141         }
 142
 143         return NULL;
 144     }
 145
 146     /* Set default values */
 147     player->pl_Reserved0 = -1;            /* AlarmSigBit */
 148     player->pl_Flags |= PLAYERF_READY;
 149
 150     D(bug("Calling SetPlayerAttrsA()\n"));
 151
 152     if (SetPlayerAttrsA(player, tagList))
 153     {
 154         return player;
 155     }
 156     else
 157     {
 158         return NULL;
 159     }
 160
 161     AROS_LIBFUNC_EXIT
 162 } /* CreatePlayerA */