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/****************************************************************
14This file defines the messages sent between a Subscriber and a
15Server.  Changes to the protocol should be noted here and appropriate
16modifications made to Subscriber.cpp and any servers (currently
17the audio_server is the only one).
18
19BufferMsgs defines a message-based interface, not a class
20interface.  A BufferMsgs receives messages from Subscribers via the
21BMessenger class.
22
23Here are the messages that must be supported for the base Subscriber
24class and the replies that a server will send.  Specific Servers
25may support other messages as well.
26
27====
28Acquire a stream-id for subsequent operations.
29'resource' is a server-specific value that specifies the resource
30to which the client wants access.
31
32Upon success, the server replies with 'stream_id' (used for
33subsequent operations).
34
35GET_STREAM_ID int32("resource")
36=> GET_STREAM_ID int32("stream_id")
37=> ERROR_RETURN int32("error")
38
39====
40Acquire 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
43or if it will block until access is granted.  'sem' is a semaphore
44used to indicate that the stream has released a buffer.
45
46Upon success, the server replies with 'subscriber_id' (used for
47subsequent operations).
48
49SUBSCRIBE 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====
57Relinquish access to the stream.
58
59UNSUBSCRIBE int32("subscriber_id")
60=> UNSUBSCRIBE
61=> ERROR_RETURN int32("error")
62
63====
64Join the stream at the specified position and start receiving buffers
65of data.
66ENTER_STREAM int32("subscriber_id")
67			 int32("neighbor")
68			 Bool("before")
69=> ENTER_STREAM
70=> ERROR_RETURN int32("error")
71
72====
73Issue a request to stop receiving buffers.  More buffers may continue
74to arrive, but you must keep acquiring_ and releasing_ them until you
75get one for which is_last_buffer() is true.  Then you can stop.
76
77EXIT_STREAM int32("subscriber_id")
78=> EXIT_STREAM
79=> ERROR_RETURN int32("error")
80
81====
82Get information about a particular buffer stream.
83
84GET_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====
91Set information about a particular buffer stream.
92
93SET_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====
104Return the subscriber id of the index'th subscriber sharing the
105stream with the given subscriber.
106
107SUBSCRIBER_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 */
117enum {
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
131