source: roaraudio/include/libroar/services.h @ 5880:0a5f9633d5ea

Last change on this file since 5880:0a5f9633d5ea was 5880:0a5f9633d5ea, checked in by phi, 11 years ago

updated prototype

File size: 8.1 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:
67struct roar_client;
68struct roar_service_clients {
69 // get list of client IDs.
70 // buffer is passed as ids, buffer size (in elements) is passed as len.
71 // returns the number of elements stored in ids or -1 on error.
72 ssize_t (*list)(int * ids, size_t len);
73 // get the number of clients. See also comments above on what.
74 ssize_t (*num)(enum roar_service_num what);
75 // get a client by ID. The object returned is a copy and must not be motified.
76 int (*get)(int id, struct roar_client * client);
77 // kick a client by ID. The reason for the kick is stored in error and msg.
78 // if msg is NULL it defaults to roar_error2str(error).
79 int (*kick)(int id, int error, const char * msg);
80 // return status of client as returned by CPI's status() callback.
81 int (*status)(int id);
82
83 // optional functions follow:
84
85 // set PID, UID and/or GID for client.
86 // if any ID is -1 the old value is not touched if clear is false.
87 // if clear is false IDs passed as -1 are reset to 'not set'.
88 // if altering IDs changes the permissions of a given client is up to the
89 // provider.
90 int (*set_ids)(int id, int clear, int pid, int uid, int gid);
91 // set the name of the client.
92 // the name is copied within this call so the bufer holding it can be freed.
93 int (*set_name)(int id, const char * name);
94 // this will change the protocol of the client.
95 int (*set_proto)(int id, int proto);
96 // this execes the stream.
97 // the stream must be owned by the client.
98 // if stream is -1 the client is execed.
99 // This will result in the client be completly reset to a state
100 // as directly after accept(). This must be followed by a call to set_proto().
101 int (*exec)(int id, int stream);
102};
103
104// streams:
105struct roar_service_streams {
106 // get list of stream IDs.
107 // buffer is passed as ids, buffer size (in elements) is passed as len.
108 // returns the number of elements stored in ids or -1 on error.
109 ssize_t (*list)(int * ids, size_t len);
110 // get the number of streams. See also comments above on what.
111 ssize_t (*num)(enum roar_service_num what);
112 // get a stream by ID. The object returned is a copy and must not be motified.
113 int (*get)(int id, struct roar_stream * s, struct roar_stream_info * info);
114 // kick a stream by ID. The reason for the kick is stored in error and msg.
115 // if msg is NULL it defaults to roar_error2str(error).
116 int (*kick)(int id, int error, const char * msg);
117
118 // optional functions follow:
119
120 // create a new stream.
121 // if parent is set to -1 a normal stream is created.
122 // if it is set to the ID of an existing stream it is created as child/virtual stream.
123 // if mixer is set to -1 the default mixer is used.
124 int (*new)(const struct roar_audio_info * info, int dir, int parent, int mixer);
125 // get the ID of the client owning the stream.
126 int (*get_client)(int id);
127 // set the owner of the stream.
128 // if the stream is already owned by a client it is moved if possible.
129 int (*set_client)(int id, int client);
130 // set role of stream.
131 // if role is passed as -1 the role is cleared.
132 int (*set_role)(int id, int role);
133 // alter stream flags.
134 int (*set_flag)(int id, uint32_t flags, int action);
135 // get name of stream.
136 // the buffer returned in *name must be freed using roar_mm_free().
137 int (*get_name)(int id, char ** name);
138 // set name of stream.
139 // stream name will be copied so the buffer can be freed after this call.
140 // passing NULL will unset the stream name.
141 int (*set_name)(int id, const char * name);
142 // set volume and rpg settings.
143 // If mixer or rpg is NULL the corresponding setting is not touched.
144 // if both are NULL this does nothing.
145 int (*set_volume)(int id, const struct roar_mixer_settings * mixer, const struct roar_stream_rpg * rpg);
146};
147
148// about:
149#define ROAR_SERVICE_ABOUT_NAME "about"
150#define ROAR_SERVICE_ABOUT_ABI  "1.0beta9"
151struct roar_service_about {
152 int (*show)(const struct roar_dl_libraryname * libname);
153};
154
155// help:
156#define ROAR_SERVICE_HELP_NAME "help"
157#define ROAR_SERVICE_HELP_ABI  "1.0beta9"
158struct roar_service_help {
159 int (*show)(const struct roar_dl_libraryname * libname, const char * topic);
160};
161
162// prefs:
163// procctl:
164#define ROAR_SERVICE_PROCCTL_ERROR     ((uint_least32_t)0xFFFFFFFFUL)
165#define ROAR_SERVICE_PROCCTL_NONE      ((uint_least32_t)0x00000000UL)
166#define ROAR_SERVICE_PROCCTL_ALL       ((uint_least32_t)0x7FFFFFFFUL)
167#define ROAR_SERVICE_PROCCTL_CONFIG    ((uint_least32_t)0x00000001UL)
168#define ROAR_SERVICE_PROCCTL_LOGFILE   ((uint_least32_t)0x00000002UL)
169#define ROAR_SERVICE_PROCCTL_PIDFILE   ((uint_least32_t)0x00000004UL)
170
171struct roar_service_procctl {
172 // terminate the process.
173 // rv is the return POSIX return code.
174 // a value of zero means no error.
175 // a value of -1 means the provider should decide the value
176 // based on the other parameters.
177 // a value smaller than -1 is not allowed.
178 // all other values indicate some kind of error.
179 // error and msg give a closer information why the process is terminated.
180 // those can be be used in case rv is set to -1. they can also be printed
181 // or logged by the the provider for later inspection.
182 int (*exit)(int rv, int error, const char * msg);
183
184
185 // optional functions follow:
186
187 // restart the process.
188 int (*restart)(void);
189 // daemonize the process.
190 // the process is moved into background, detaching from the console.
191 int (*daemonize)(void);
192 // reload config or other parts. See above.
193 int (*reload)(uint_least32_t what);
194 // reopen logfiles or other parts. See above.
195 int (*reopen)(uint_least32_t what);
196};
197
198// queue:
199struct roar_service_queue {
200 ssize_t (*list)(int * ids, size_t len);
201 ssize_t (*num)(enum roar_service_num what);
202 int (*get_name)(int id, char ** name);
203 // status?
204 int (*play)(int id);
205 int (*stop)(int id);
206 int (*pause)(int id, int how);
207 int (*next)(int id);
208 int (*prev)(int id);
209};
210
211#endif
212
213//ll
Note: See TracBrowser for help on using the repository browser.