source: roaraudio/include/libroar/services.h @ 5887:9aa2beedb9a4

Last change on this file since 5887:9aa2beedb9a4 was 5887:9aa2beedb9a4, checked in by phi, 7 years ago

finalized service API for "client" universal service

File size: 8.2 KB
Line 
1//services.h:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2008-2013
5 *
6 *  This file is part of libroar a part of RoarAudio,
7 *  a cross-platform sound system for both, home and professional use.
8 *  See README for details.
9 *
10 *  This file is free software; you can redistribute it and/or modify
11 *  it under the terms of the GNU General Public License version 3
12 *  as published by the Free Software Foundation.
13 *
14 *  libroar is distributed in the hope that it will be useful,
15 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *  GNU General Public License for more details.
18 *
19 *  You should have received a copy of the GNU General Public License
20 *  along with this software; see the file COPYING.  If not, write to
21 *  the Free Software Foundation, 51 Franklin Street, Fifth Floor,
22 *  Boston, MA 02110-1301, USA.
23 *
24 *  NOTE for everyone want's to change something and send patches:
25 *  read README and HACKING! There a addition information on
26 *  the license of this document you need to read before you send
27 *  any patches.
28 *
29 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
30 *  or libpulse*:
31 *  The libs libroaresd, libroararts and libroarpulse link this lib
32 *  and are therefore GPL. Because of this it may be illigal to use
33 *  them with any software that uses libesd, libartsc or libpulse*.
34 */
35
36#ifndef _LIBROARSERVICES_H_
37#define _LIBROARSERVICES_H_
38
39#include "libroar.h"
40
41enum roar_service_num {
42 // Error value in case any function returns this type.
43 // roar_error must be set on return.
44 ROAR_SERVICE_NUM_ERROR   = -1,
45#define ROAR_SERVICE_NUM_ERROR ROAR_SERVICE_NUM_ERROR
46 // reserved for future use.
47 ROAR_SERVICE_NUM_DEFAULT =  0,
48//#define ROAR_SERVICE_NUM_DEFAULT ROAR_SERVICE_NUM_DEFAULT
49 // current number of objects.
50 ROAR_SERVICE_NUM_CURRENT =  1,
51#define ROAR_SERVICE_NUM_CURRENT ROAR_SERVICE_NUM_CURRENT
52 // minumum number of objects. Optional.
53 ROAR_SERVICE_NUM_MIN,
54#define ROAR_SERVICE_NUM_MIN ROAR_SERVICE_NUM_MIN
55 // maximum number of objects. Optional.
56 ROAR_SERVICE_NUM_MAX,
57#define ROAR_SERVICE_NUM_MAX ROAR_SERVICE_NUM_MAX
58 // average number of objects. Optional.
59 ROAR_SERVICE_NUM_AVG,
60#define ROAR_SERVICE_NUM_AVG ROAR_SERVICE_NUM_AVG
61 // Hint for buffer size used to list(). list() can still return 'buffer to short'.
62 ROAR_SERVICE_NUM_BUFFER,
63#define ROAR_SERVICE_NUM_BUFFER ROAR_SERVICE_NUM_BUFFER
64};
65
66// clients:
67#define ROAR_SERVICE_CLIENT_NAME "client"
68#define ROAR_SERVICE_CLIENT_ABI  "1.0beta9-pr1"
69struct roar_client;
70struct roar_service_client {
71 // get list of client IDs.
72 // buffer is passed as ids, buffer size (in elements) is passed as len.
73 // returns the number of elements stored in ids or -1 on error.
74 ssize_t (*list)(int * ids, size_t len);
75 // get the number of clients. See also comments above on what.
76 ssize_t (*num)(enum roar_service_num what);
77 // get a client by ID. The object returned is a copy and must not be motified.
78 int (*get)(int id, struct roar_client * client);
79 // kick a client by ID. The reason for the kick is stored in error and msg.
80 // if msg is NULL it defaults to roar_error2str(error).
81 int (*kick)(int id, int error, const char * msg);
82 // return status of client as returned by CPI's status() callback.
83 int (*status)(int id);
84
85 // optional functions follow:
86
87 // set PID, UID and/or GID for client.
88 // if any ID is -1 the old value is not touched if clear is false.
89 // if clear is false IDs passed as -1 are reset to 'not set'.
90 // if altering IDs changes the permissions of a given client is up to the
91 // provider.
92 int (*set_ids)(int id, int clear, int pid, int uid, int gid);
93 // set the name of the client.
94 // the name is copied within this call so the bufer holding it can be freed.
95 int (*set_name)(int id, const char * name);
96 // this will change the protocol of the client.
97 int (*set_proto)(int id, int proto);
98 // this execes the stream.
99 // the stream must be owned by the client.
100 // if stream is -1 the client is execed.
101 // This will result in the client be completly reset to a state
102 // as directly after accept(). This must be followed by a call to set_proto().
103 int (*exec)(int id, int stream);
104};
105
106// streams:
107struct roar_stream_info;
108struct roar_stream_rpg;
109struct roar_service_stream {
110 // get list of stream IDs.
111 // buffer is passed as ids, buffer size (in elements) is passed as len.
112 // returns the number of elements stored in ids or -1 on error.
113 ssize_t (*list)(int * ids, size_t len);
114 // get the number of streams. See also comments above on what.
115 ssize_t (*num)(enum roar_service_num what);
116 // get a stream by ID. The object returned is a copy and must not be motified.
117 int (*get)(int id, struct roar_stream * s, struct roar_stream_info * info);
118 // kick a stream by ID. The reason for the kick is stored in error and msg.
119 // if msg is NULL it defaults to roar_error2str(error).
120 int (*kick)(int id, int error, const char * msg);
121
122 // optional functions follow:
123
124 // create a new stream.
125 // if parent is set to -1 a normal stream is created.
126 // if it is set to the ID of an existing stream it is created as child/virtual stream.
127 // if mixer is set to -1 the default mixer is used.
128 int (*new)(const struct roar_audio_info * info, int dir, int parent, int mixer);
129 // get the ID of the client owning the stream.
130 int (*get_client)(int id);
131 // set the owner of the stream.
132 // if the stream is already owned by a client it is moved if possible.
133 int (*set_client)(int id, int client);
134 // set role of stream.
135 // if role is passed as -1 the role is cleared.
136 int (*set_role)(int id, int role);
137 // alter stream flags.
138 int (*set_flag)(int id, uint32_t flags, int action);
139 // get name of stream.
140 // the buffer returned in *name must be freed using roar_mm_free().
141 int (*get_name)(int id, char ** name);
142 // set name of stream.
143 // stream name will be copied so the buffer can be freed after this call.
144 // passing NULL will unset the stream name.
145 int (*set_name)(int id, const char * name);
146 // set volume and rpg settings.
147 // If mixer or rpg is NULL the corresponding setting is not touched.
148 // if both are NULL this does nothing.
149 int (*set_volume)(int id, const struct roar_mixer_settings * mixer, const struct roar_stream_rpg * rpg);
150};
151
152// about:
153#define ROAR_SERVICE_ABOUT_NAME "about"
154#define ROAR_SERVICE_ABOUT_ABI  "1.0beta9"
155struct roar_service_about {
156 int (*show)(const struct roar_dl_libraryname * libname);
157};
158
159// help:
160#define ROAR_SERVICE_HELP_NAME "help"
161#define ROAR_SERVICE_HELP_ABI  "1.0beta9"
162struct roar_service_help {
163 int (*show)(const struct roar_dl_libraryname * libname, const char * topic);
164};
165
166// prefs:
167// procctl:
168#define ROAR_SERVICE_PROCCTL_ERROR     ((uint_least32_t)0xFFFFFFFFUL)
169#define ROAR_SERVICE_PROCCTL_NONE      ((uint_least32_t)0x00000000UL)
170#define ROAR_SERVICE_PROCCTL_ALL       ((uint_least32_t)0x7FFFFFFFUL)
171#define ROAR_SERVICE_PROCCTL_CONFIG    ((uint_least32_t)0x00000001UL)
172#define ROAR_SERVICE_PROCCTL_LOGFILE   ((uint_least32_t)0x00000002UL)
173#define ROAR_SERVICE_PROCCTL_PIDFILE   ((uint_least32_t)0x00000004UL)
174
175struct roar_service_procctl {
176 // terminate the process.
177 // rv is the return POSIX return code.
178 // a value of zero means no error.
179 // a value of -1 means the provider should decide the value
180 // based on the other parameters.
181 // a value smaller than -1 is not allowed.
182 // all other values indicate some kind of error.
183 // error and msg give a closer information why the process is terminated.
184 // those can be be used in case rv is set to -1. they can also be printed
185 // or logged by the the provider for later inspection.
186 int (*exit)(int rv, int error, const char * msg);
187
188 // optional functions follow:
189
190 // restart the process.
191 int (*restart)(void);
192 // daemonize the process.
193 // the process is moved into background, detaching from the console.
194 int (*daemonize)(void);
195 // reload config or other parts. See above.
196 int (*reload)(uint_least32_t what);
197 // reopen logfiles or other parts. See above.
198 int (*reopen)(uint_least32_t what);
199};
200
201// queue:
202struct roar_service_queue {
203 ssize_t (*list)(int * ids, size_t len);
204 ssize_t (*num)(enum roar_service_num what);
205 int (*get_name)(int id, char ** name);
206 // status?
207 int (*play)(int id);
208 int (*stop)(int id);
209 int (*pause)(int id, int how);
210 int (*next)(int id);
211 int (*prev)(int id);
212};
213
214#endif
215
216//ll
Note: See TracBrowser for help on using the repository browser.