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
|
/**
* mds — A micro-display server
* Copyright © 2014 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_LIBMDSSERVER_MDS_MESSAGE_H
#define MDS_LIBMDSSERVER_MDS_MESSAGE_H
#include <stddef.h>
#define MDS_MESSAGE_T_VERSION 0
/**
* Message passed between a server and a client or between two of either
*/
typedef struct mds_message
{
/**
* The headers in the message, each element in this list
* as an unparsed header, it consists of both the header
* name and its associated value, joined by ": ". A header
* cannot be `NULL` (unless its memory allocation failed,)
* but `headers` itself is NULL if there are no headers.
* The "Length" should be included in this list.
*/
char** headers;
/**
* The number of headers in the message
*/
size_t header_count;
/**
* The payload of the message, `NULL` if none (of zero-length)
*/
char* payload;
/**
* The size of the payload
*/
size_t payload_size;
/**
* How much of the payload that has been stored (internal data)
*/
size_t payload_ptr;
/**
* Internal buffer for the reading function (internal data)
*/
char* buffer;
/**
* The size allocated to `buffer` (internal data)
*/
size_t buffer_size;
/**
* The number of bytes used in `buffer` (internal data)
*/
size_t buffer_ptr; /* TODO: whould it be better to use a ring buffer? */
/**
* 0 while reading headers, 1 while reading payload, and 2 when done (internal data)
*/
int stage;
} mds_message_t;
/**
* Initialsie a message slot so that it can
* be used by `mds_message_read`.
*
* @param this Memory slot in which to store the new message
* @return Non-zero on error, errno will be set accordingly.
* Destroy the message on error.
*/
int mds_message_initialise(mds_message_t* restrict this);
/**
* Release all resources in a message, should
* be done even if initialisation fails
*
* @param this The message
*/
void mds_message_destroy(mds_message_t* restrict this);
/**
* Read the next message from a file descriptor
*
* @param this Memory slot in which to store the new message
* @param fd The file descriptor
* @return Non-zero on error or interruption, errno will be
* set accordingly. Destroy the message on error,
* be aware that the reading could have been
* interrupted by a signal rather than canonical error.
* If -2 is returned errno will not have been set,
* -2 indicates that the message is malformated,
* which is a state that cannot be recovered from.
*/
int mds_message_read(mds_message_t* restrict this, int fd);
/**
* Get the required allocation size for `data` of the
* function `mds_message_marshal`
*
* @param this The message
* @param include_buffer Whether buffer should be marshalled (state serialisation, not communication)
* @return The size of the message when marshalled
*/
size_t mds_message_marshal_size(const mds_message_t* restrict this, int include_buffer) __attribute__((pure));
/**
* Marshal a message, this can be used both when serialising
* the servers state or to get the byte stream to send to
* the recipient of the message
*
* @param this The message
* @param data Output buffer for the marshalled data
* @param include_buffer Whether buffer should be marshalled (state serialisation, not communication)
*/
void mds_message_marshal(const mds_message_t* restrict this, char* restrict data, int include_buffer);
/**
* Unmarshal a message, it is assumed that the buffer is marshalled
*
* @param this Memory slot in which to store the new message
* @param data In buffer with the marshalled data
* @return Non-zero on error, errno will be set accordingly.
* Destroy the message on error.
*/
int mds_message_unmarshal(mds_message_t* restrict this, char* restrict data);
#endif
|
