src/kits/media/legacy/OldBufferMsgs.h

   1 /* ++++++++++
   2
   3    FILE:  BufferMsgs.h
   4
   5    Copyright (c) 1995-1997 by Be Incorporated.  All Rights Reserved.
   6
   7 +++++ */
   8 #ifndef _BUFFER_MSGS_H
   9 #define _BUFFER_MSGS_H
  10
  11 #include <SupportDefs.h>
  12
  13 /****************************************************************
  14 This file defines the messages sent between a Subscriber and a
  15 Server.  Changes to the protocol should be noted here and appropriate
  16 modifications made to Subscriber.cpp and any servers (currently
  17 the audio_server is the only one).
  18
  19 BufferMsgs defines a message-based interface, not a class
  20 interface.  A BufferMsgs receives messages from Subscribers via the
  21 BMessenger class.
  22
  23 Here are the messages that must be supported for the base Subscriber
  24 class and the replies that a server will send.  Specific Servers
  25 may support other messages as well.
  26
  27 ====
  28 Acquire a stream-id for subsequent operations.
  29 'resource' is a server-specific value that specifies the resource
  30 to which the client wants access.
  31
  32 Upon success, the server replies with 'stream_id' (used for
  33 subsequent operations).
  34
  35 GET_STREAM_ID int32("resource")
  36 => GET_STREAM_ID int32("stream_id")
  37 => ERROR_RETURN int32("error")
  38
  39 ====
  40 Acquire access to a stream for subsequent operations.
  41 'stream_id' specifies the stream to which the client wants access.
  42 'will_wait' determines if the client will receive an immediate reply
  43 or if it will block until access is granted.  'sem' is a semaphore
  44 used to indicate that the stream has released a buffer.
  45
  46 Upon success, the server replies with 'subscriber_id' (used for
  47 subsequent operations).
  48
  49 SUBSCRIBE String("name")
  50                   int32("stream_id")
  51                   int32("sem")
  52                   Bool("will_wait")
  53 => SUBSCRIBE int32("subscriber_id")
  54 => ERROR_RETURN int32("error")
  55
  56 ====
  57 Relinquish access to the stream.
  58
  59 UNSUBSCRIBE int32("subscriber_id")
  60 => UNSUBSCRIBE
  61 => ERROR_RETURN int32("error")
  62
  63 ====
  64 Join the stream at the specified position and start receiving buffers
  65 of data.
  66 ENTER_STREAM int32("subscriber_id")
  67                          int32("neighbor")
  68                          Bool("before")
  69 => ENTER_STREAM
  70 => ERROR_RETURN int32("error")
  71
  72 ====
  73 Issue a request to stop receiving buffers.  More buffers may continue
  74 to arrive, but you must keep acquiring_ and releasing_ them until you
  75 get one for which is_last_buffer() is true.  Then you can stop.
  76
  77 EXIT_STREAM int32("subscriber_id")
  78 => EXIT_STREAM
  79 => ERROR_RETURN int32("error")
  80
  81 ====
  82 Get information about a particular buffer stream.
  83
  84 GET_STREAM_PARAMS int32("stream_id")
  85 => GET_STREAM_PARAMS int32("buffer_size")
  86                                          int32("buffer_count")
  87                                          Bool("is_running")
  88                                          int32("subscriber_count")
  89 => ERROR_RETURN int32("error")
  90 ====
  91 Set information about a particular buffer stream.
  92
  93 SET_STREAM_PARAMS int32("stream_id")
  94                                   int32("buffer_size")  <<optional>>
  95                                   int32("buffer_count") <<optional>>
  96                                   Bool("is_running")    <<optional>>
  97 => SET_STREAM_PARAMS int32("buffer_size")
  98                                          int32("buffer_count")
  99                                          Bool("is_running")
 100                                          int32("subscriber_count")
 101 => ERROR_RETURN int32("error")
 102
 103 ====
 104 Return the subscriber id of the index'th subscriber sharing the
 105 stream with the given subscriber.
 106
 107 SUBSCRIBER_INFO int32("subscriber_id")
 108 => SUBSCRIBER_INFO String("subscriber_name")
 109                                    int32("stream_id")           // granted access to
 110                                    int32("position")            // position (if active) or -1
 111 => ERROR_RETURN int32("error")
 112
 113 <end of long comment>
 114 ****************************************************************/
 115
 116 /* message values */
 117 enum {
 118   DEBUG_SERVER = 99,
 119   SUBSCRIBE,
 120   UNSUBSCRIBE,
 121   ENTER_STREAM,
 122   EXIT_STREAM,
 123   GET_STREAM_PARAMETERS,
 124   SET_STREAM_PARAMETERS,
 125   GET_STREAM_ID,
 126   SUBSCRIBER_INFO,
 127   ERROR_RETURN
 128   };
 129
 130 #endif                  // #ifndef _BUFFER_MSGS_H