aboutsummaryrefslogtreecommitdiffstats
path: root/src/libmdsclient/comm.h
blob: bb8f880455e3daf50e96897a2d2cc7aa7f449134 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
/**
 * mds — A micro-display server
 * Copyright © 2014, 2015, 2016  Mattias Andrée (maandree@member.fsf.org)
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef MDS_LIBMDSCLIENT_COMM_H
#define MDS_LIBMDSCLIENT_COMM_H


#include "address.h"

#include <stdint.h>
#include <stddef.h>
#include <pthread.h>
#include <time.h>
#include <errno.h>
#include <inttypes.h>



/**
 * A connection to the display server
 */
typedef struct libmds_connection
{
  /**
   * The file descriptor of the socket
   * connected to the display server,
   * -1 if not connected
   */
  int socket_fd;
  
  /**
   * The ID of the _previous_ message
   */
  uint32_t message_id;
  
  /**
   * The client ID, `NULL` if anonymous
   */
  char* client_id;
  
  /**
   * Mutex used to hinder concurrent modification
   * and concurrent message passing
   * 
   * This mutex is a fast mutex, a thread may not
   * lock it more than once
   */
  pthread_mutex_t mutex;
  
  /**
   * Whether `mutex` is initialised
   */
  int mutex_initialised;
  
} libmds_connection_t;


/**
 * Initialise a connection descriptor
 * 
 * @param   this  The connection descriptor
 * @return        Zero on success, -1 on error, `ernno`
 *                will have been set accordingly on error
 * 
 * @throws  EAGAIN  See pthread_mutex_init(3)
 * @throws  ENOMEM  See pthread_mutex_init(3)
 * @throws  EPERM   See pthread_mutex_init(3)
 */
__attribute__((nonnull))
int libmds_connection_initialise(libmds_connection_t* restrict this);

/**
 * Allocate and initialise a connection descriptor
 * 
 * @return  The connection descriptor, `NULL` on error,
 *          `errno` will have been set accordingly on error
 * 
 * @throws  ENOMEM  Out of memory. Possibly, the process hit the RLIMIT_AS or
 *                  RLIMIT_DATA limit described in getrlimit(2).
 * @throws  EAGAIN  See pthread_mutex_init(3)
 * @throws  EPERM   See pthread_mutex_init(3)
 */
libmds_connection_t* libmds_connection_create(void);

/**
 * Release all resources held by a connection descriptor
 * 
 * @param  this  The connection descriptor, may be `NULL`
 */
void libmds_connection_destroy(libmds_connection_t* restrict this);

/**
 * Release all resources held by a connection descriptor,
 * and release the allocation of the connection descriptor
 * 
 * @param  this  The connection descriptor, may be `NULL`
 */
void libmds_connection_free(libmds_connection_t* restrict this);

/**
 * Connect to the display server
 * 
 * @param   this     The connection descriptor, must not be `NULL`
 * @param   display  Pointer to `NULL` to select display be looking at
 *                   the environment. Pointer to a string with the
 *                   address (formatted as the environment variable
 *                   MDS_DISPLAY) if manually specified. The pointer
 *                   itself must not be `NULL`; it will be updated
 *                   with the address if it points to NULL.
 * @return           Zero on success, -1 on error. On error, `display`
 *                   will point to `NULL` if MDS_DISPLAY is not defiend,
 *                   otherwise, `errno` will have been set to describe
 *                   the error.
 * 
 * @throws  EFAULT        If the display server's address is not properly
 *                        formatted, or specifies an unsupported protocol,
 *                        `libmds_parse_display_adress` can be used to
 *                        figure out what is wrong.
 * @throws  ENAMETOOLONG  The filename of the target socket is too long
 * @throws                Any error specified for socket(2)
 * @throws                Any error specified for connect(2), except EINTR
 */
__attribute__((nonnull))
int libmds_connection_establish(libmds_connection_t* restrict this, const char** restrict display);

/**
 * Connect to the display server
 * 
 * @param   this     The connection descriptor, must not be `NULL`
 * @param   address  The address to connect to, must not be `NULL`,
 *                   and must be the result of a successful call to
 *                   `libmds_parse_display_address`
 * @return           Zero on success, -1 on error. On error, `display`
 *                   will point to `NULL` if MDS_DISPLAY is not defiend,
 *                   otherwise, `errno` will have been set to describe
 *                   the error.
 * 
 * @throws  Any error specified for socket(2)
 * @throws  Any error specified for connect(2), except EINTR
 */
__attribute__((nonnull))
int libmds_connection_establish_address(libmds_connection_t* restrict this,
					const libmds_display_address_t* restrict address);

/**
 * Wrapper for `libmds_connection_send_unlocked` that locks
 * the mutex of the connection
 * 
 * @param   this     The connection descriptor, must not be `NULL`
 * @param   message  The message to send, must not be `NULL`
 * @param   length   The length of the message, should be positive
 * @return           The number of sent bytes. Less than `length` on error,
 *                   `ernno` will have been set accordingly on error
 * 
 * @throws  EACCES        See send(2)
 * @throws  EWOULDBLOCK   See send(2), only if the socket has been modified to nonblocking
 * @throws  EBADF         See send(2)
 * @throws  ECONNRESET    If connection was lost
 * @throws  EDESTADDRREQ  See send(2)
 * @throws  EFAULT        See send(2)
 * @throws  EINVAL        See send(2)
 * @throws  ENOBUFS       See send(2)
 * @throws  ENOMEM        See send(2)
 * @throws  ENOTCONN      See send(2)
 * @throws  ENOTSOCK      See send(2)
 * @throws  EPIPE         See send(2)
 * @throws                See pthread_mutex_lock(3)
 */
__attribute__((nonnull))
size_t libmds_connection_send(libmds_connection_t* restrict this, const char* restrict message, size_t length);

/**
 * Send a message to the display server, without locking the
 * mutex of the conncetion
 * 
 * @param   this                   The connection descriptor, must not be `NULL`
 * @param   message                The message to send, must not be `NULL`
 * @param   length                 The length of the message, should be positive
 * @param   continue_on_interrupt  Whether to continue sending if interrupted by a signal
 * @return                         The number of sent bytes. Less than `length` on error,
 *                                 `ernno` will have been set accordingly on error
 * 
 * @throws  EACCES        See send(2)
 * @throws  EWOULDBLOCK   See send(2), only if the socket has been modified to nonblocking
 * @throws  EBADF         See send(2)
 * @throws  ECONNRESET    If connection was lost
 * @throws  EDESTADDRREQ  See send(2)
 * @throws  EFAULT        See send(2)
 * @throws  EINTR         If interrupted by a signal, only if `continue_on_interrupt' is zero
 * @throws  EINVAL        See send(2)
 * @throws  ENOBUFS       See send(2)
 * @throws  ENOMEM        See send(2)
 * @throws  ENOTCONN      See send(2)
 * @throws  ENOTSOCK      See send(2)
 * @throws  EPIPE         See send(2)
 */
__attribute__((nonnull))
size_t libmds_connection_send_unlocked(libmds_connection_t* restrict this, const char* restrict message,
				       size_t length, int continue_on_interrupt);

/**
 * Lock the connection descriptor for being modified,
 * or used to send data to the display, by another thread
 * 
 * @param   this:libmds_connection_t*  The connection descriptor, must not be `NULL`
 * @return  :int                       Zero on success, -1 on error, `errno`
 *                                     will have been set accordingly on error
 * 
 * @throws  See pthread_mutex_lock(3)
 */
#define libmds_connection_lock(this) \
  (errno = pthread_mutex_lock(&((this)->mutex)), (errno ? 0 : -1))

/**
 * Lock the connection descriptor for being modified,
 * or used to send data to the display, by another thread
 * 
 * @param   this:libmds_connection_t*  The connection descriptor, must not be `NULL`
 * @return  :int                       Zero on success, -1 on error, `errno`
 *                                     will have been set accordingly on error
 * 
 * @throws  See pthread_mutex_trylock(3)
 */
#define libmds_connection_trylock(this) \
  (errno = pthread_mutex_trylock(&((this)->mutex)), (errno ? 0 : -1))

/**
 * Lock the connection descriptor for being modified,
 * or used to send data to the display, by another thread
 * 
 * @param   this:libmds_connection_t*                 The connection descriptor, must not be `NULL`
 * @param   deadline:const struct timespec *restrict  The absolute `CLOCK_REALTIME` time when the
 *                                                    function shall fail, must not be `NULL`
 * @return  :int                                      Zero on success, -1 on error, `errno`
 *                                                    will have been set accordingly on error
 * 
 * @throws  See pthread_mutex_timedlock(3)
 */
#define libmds_connection_timedlock(this, deadline)  \
  (errno = pthread_mutex_timedlock(&((this)->mutex), deadline), (errno ? 0 : -1))

/**
 * Undo the action of `libmds_connection_lock`, `libmds_connection_trylock`
 * or `libmds_connection_timedlock`
 * 
 * @param   this:libmds_connection_t*  The connection descriptor, must not be `NULL`
 * @return  :int                       Zero on success, -1 on error, `errno`
 *                                     will have been set accordingly on error
 * 
 * @throws  See pthread_mutex_unlock(3)
 */
#define libmds_connection_unlock(this)  \
  (errno = pthread_mutex_unlock(&((this)->mutex)), (errno ? 0 : -1))

/**
 * Arguments for `libmds_compose` to compose the `Client ID`-header
 * 
 * @param  this: libmds_connection_t*  The connection descriptor, must not be `NULL`
 */
#define LIBMDS_HEADER_CLIENT_ID(this)  \
  "?Client ID: %s", (this)->client_id != NULL, (this)->client_id

/**
 * Arguments for `libmds_compose` to compose the `Message ID`-header
 * 
 * @param  this: libmds_connection_t*  The connection descriptor, must not be `NULL`
 */
#define LIBMDS_HEADER_MESSAGE_ID(this)  \
  "Message ID: %"PRIu32, (this)->message_id

/**
 * Arguments for `libmds_compose` to compose the standard headers:
 * `Client ID` and `Message ID`
 * 
 * @param  this: libmds_connection_t*  The connection descriptor, must not be `NULL`
 */
#define LIBMDS_HEADERS_STANDARD(this)  \
  LIBMDS_HEADER_CLIENT_ID(this), LIBMDS_HEADER_MESSAGE_ID(this)



#endif