Index: include/libroar/services.h
===================================================================
--- include/libroar/services.h	(revision 5836)
+++ include/libroar/services.h	(revision 5879)
@@ -39,19 +39,109 @@
 #include "libroar.h"
 
+enum roar_service_num {
+ // Error value in case any function returns this type.
+ // roar_error must be set on return.
+ ROAR_SERVICE_NUM_ERROR   = -1,
+#define ROAR_SERVICE_NUM_ERROR ROAR_SERVICE_NUM_ERROR
+ // reserved for future use.
+ ROAR_SERVICE_NUM_DEFAULT =  0,
+//#define ROAR_SERVICE_NUM_DEFAULT ROAR_SERVICE_NUM_DEFAULT
+ // current number of objects.
+ ROAR_SERVICE_NUM_CURRENT =  1,
+#define ROAR_SERVICE_NUM_CURRENT ROAR_SERVICE_NUM_CURRENT
+ // minumum number of objects. Optional.
+ ROAR_SERVICE_NUM_MIN,
+#define ROAR_SERVICE_NUM_MIN ROAR_SERVICE_NUM_MIN
+ // maximum number of objects. Optional.
+ ROAR_SERVICE_NUM_MAX,
+#define ROAR_SERVICE_NUM_MAX ROAR_SERVICE_NUM_MAX
+ // average number of objects. Optional.
+ ROAR_SERVICE_NUM_AVG,
+#define ROAR_SERVICE_NUM_AVG ROAR_SERVICE_NUM_AVG
+ // Hint for buffer size used to list(). list() can still return 'buffer to short'.
+ ROAR_SERVICE_NUM_BUFFER,
+#define ROAR_SERVICE_NUM_BUFFER ROAR_SERVICE_NUM_BUFFER
+};
+
 // clients:
 struct roar_client;
 struct roar_service_clients {
+ // get list of client IDs.
+ // buffer is passed as ids, buffer size (in elements) is passed as len.
+ // returns the number of elements stored in ids or -1 on error.
  ssize_t (*list)(int * ids, size_t len);
- ssize_t (*num)(void);
+ // get the number of clients. See also comments above on what.
+ ssize_t (*num)(enum roar_service_num what);
+ // get a client by ID. The object returned is a copy and must not be motified.
  int (*get)(int id, struct roar_client * client);
- int (*kick)(int id);
+ // kick a client by ID. The reason for the kick is stored in error and msg.
+ // if msg is NULL it defaults to roar_error2str(error).
+ int (*kick)(int id, int error, const char * msg);
+ // return status of client as returned by CPI's status() callback.
+ int (*status)(int id);
+
+ // optional functions follow:
+
+ // set PID, UID and/or GID for client.
+ // if any ID is -1 the old value is not touched if clear is false.
+ // if clear is false IDs passed as -1 are reset to 'not set'.
+ // if altering IDs changes the permissions of a given client is up to the
+ // provider.
+ int (*set_ids)(int id, int clear, int pid, int uid, int gid);
+ // set the name of the client.
+ // the name is copied within this call so the bufer holding it can be freed.
+ int (*set_name)(int id, const char * name);
+ // this will change the protocol of the client.
+ int (*set_proto)(int id, int proto);
+ // this execes the stream.
+ // the stream must be owned by the client.
+ // if stream is -1 the client is execed.
+ // This will result in the client be completly reset to a state
+ // as directly after accept(). This must be followed by a call to set_proto().
+ int (*exec)(int id, int stream);
 };
 
 // streams:
 struct roar_service_streams {
+ // get list of stream IDs.
+ // buffer is passed as ids, buffer size (in elements) is passed as len.
+ // returns the number of elements stored in ids or -1 on error.
  ssize_t (*list)(int * ids, size_t len);
- ssize_t (*num)(void);
- int (*get)(int id, ...);
- int (*kick)(int id);
+ // get the number of streams. See also comments above on what.
+ ssize_t (*num)(enum roar_service_num what);
+ // get a stream by ID. The object returned is a copy and must not be motified.
+ int (*get)(int id, struct roar_stream * s, struct roar_stream_info * info);
+ // kick a stream by ID. The reason for the kick is stored in error and msg.
+ // if msg is NULL it defaults to roar_error2str(error).
+ int (*kick)(int id, int error, const char * msg);
+
+ // optional functions follow:
+
+ // create a new stream.
+ // if parent is set to -1 a normal stream is created.
+ // if it is set to the ID of an existing stream it is created as child/virtual stream.
+ // if mixer is set to -1 the default mixer is used.
+ int (*new)(const struct roar_audio_info * info, int dir, int parent, int mixer);
+ // get the ID of the client owning the stream.
+ int (*get_client)(int id);
+ // set the owner of the stream.
+ // if the stream is already owned by a client it is moved if possible.
+ int (*set_client)(int id, int client);
+ // set role of stream.
+ // if role is passed as -1 the role is cleared.
+ int (*set_role)(int id, int role);
+ // alter stream flags.
+ int (*set_flag)(int id, uint32_t flags, int action);
+ // get name of stream.
+ // the buffer returned in *name must be freed using roar_mm_free().
+ int (*get_name)(int id, char ** name);
+ // set name of stream.
+ // stream name will be copied so the buffer can be freed after this call.
+ // passing NULL will unset the stream name.
+ int (*set_name)(int id, const char * name);
+ // set volume and rpg settings.
+ // If mixer or rpg is NULL the corresponding setting is not touched.
+ // if both are NULL this does nothing.
+ int (*set_volume)(int id, const struct roar_mixer_settings * mixer, const struct roar_stream_rpg * rpg);
 };
 
@@ -72,10 +162,30 @@
 // prefs:
 // procctl:
+#define ROAR_SERVICE_PROCCTL_ERROR     ((uint_least32_t)0xFFFFFFFFUL)
+#define ROAR_SERVICE_PROCCTL_NONE      ((uint_least32_t)0x00000000UL)
+#define ROAR_SERVICE_PROCCTL_ALL       ((uint_least32_t)0x7FFFFFFFUL)
+#define ROAR_SERVICE_PROCCTL_CONFIG    ((uint_least32_t)0x00000001UL)
+#define ROAR_SERVICE_PROCCTL_LOGFILE   ((uint_least32_t)0x00000002UL)
+#define ROAR_SERVICE_PROCCTL_PIDFILE   ((uint_least32_t)0x00000004UL)
+
 struct roar_service_procctl {
+ // terminate the process.
+ // rv is the return POSIX return code.
+ // a value of zero means no error.
+ // a value smaller than zero is not allowed.
+ // all other values indicate some kind of error.
  int (*exit)(int rv);
+
+ // optional functions follow:
+
+ // restart the process.
  int (*restart)(void);
- int (*reload)(int what);
+ // daemonize the process.
+ // the process is moved into background, detaching from the console.
  int (*daemonize)(void);
- int (*reopen)(int what);
+ // reload config or other parts. See above.
+ int (*reload)(uint_least32_t what);
+ // reopen logfiles or other parts. See above.
+ int (*reopen)(uint_least32_t what);
 };
 
@@ -83,6 +193,6 @@
 struct roar_service_queue {
  ssize_t (*list)(int * ids, size_t len);
- ssize_t (*num)(void);
- int (*get_name)(int id, char * buf, size_t len);
+ ssize_t (*num)(enum roar_service_num what);
+ int (*get_name)(int id, char ** name);
  // status?
  int (*play)(int id);
