-
Notifications
You must be signed in to change notification settings - Fork 0
/
hal_socket.h
298 lines (265 loc) · 8.23 KB
/
hal_socket.h
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
298
/*
* Copyright 2016 MZ Automation GmbH
*
* This file is part of lib60870-C
*
* lib60870-C 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.
*
* lib60870-C 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 lib60870-C. If not, see <http://www.gnu.org/licenses/>.
*
* See COPYING file for the complete license text.
*/
#ifndef SOCKET_HAL_H_
#define SOCKET_HAL_H_
#include <stdint.h>
#include <stdbool.h>
/**
* \file hal_socket.h
* \brief Abstraction layer TCP/IP sockets
* Has to be implemented for CS 104 TCP/IP.
*/
#ifdef __cplusplus
extern "C" {
#endif
/*! \defgroup hal Platform (Hardware/OS) abstraction layer
*
* Platform abstraction layer. These functions have to be implemented when the library is
* to be ported to new platforms. It might not be required to implement all interfaces
* depending on the required library features.
*
* @{
*/
/**
* @defgroup HAL_SOCKET Interface to the TCP/IP stack (abstract socket layer)
*
* Thread and Socket abstraction layer. This functions have to be implemented to
* port lib60870 to a new hardware/OS platform when TCP/IP is required.
*
* @{
*/
/** Opaque reference for a server socket instance */
typedef struct sServerSocket* ServerSocket;
/** Opaque reference for a client or connection socket instance */
typedef struct sSocket* Socket;
/** Opaque reference for a set of server and socket handles */
typedef struct sHandleSet* HandleSet;
/**
* \brief Create a new connection handle set (HandleSet)
*
* \return new HandleSet instance
*/
HandleSet
Handleset_new(void);
/**
* \brief Reset the handle set for reuse
*/
void
Handleset_reset(HandleSet self);
/**
* \brief add a soecket to an existing handle set
*
* \param self the HandleSet instance
* \param sock the socket to add
*/
void
Handleset_addSocket(HandleSet self, const Socket sock);
/**
* \brief wait for a socket to become ready
*
* This function is corresponding to the BSD socket select function.
* It returns the number of sockets on which data is pending or 0 if no data is pending
* on any of the monitored connections. The function will return after "timeout" ms if no
* data is pending.
* The function shall return -1 if a socket error occures.
*
* \param self the HandleSet instance
* \param timeout in milliseconds (ms)
* \return It returns the number of sockets on which data is pending
* or 0 if no data is pending on any of the monitored connections.
* The function shall return -1 if a socket error occures.
*/
int
Handleset_waitReady(HandleSet self, unsigned int timeoutMs);
/**
* \brief destroy the HandleSet instance
*
* \param self the HandleSet instance to destroy
*/
void
Handleset_destroy(HandleSet self);
/**
* \brief Create a new TcpServerSocket instance
*
* Implementation of this function is MANDATORY if server functionality is required.
*
* \param address ip address or hostname to listen on
* \param port the TCP port to listen on
*
* \return the newly create TcpServerSocket instance
*/
ServerSocket
TcpServerSocket_create(const char* address, int port);
void
ServerSocket_listen(ServerSocket self);
/**
* \brief accept a new incoming connection (non-blocking)
*
* This function shall accept a new incoming connection. It is non-blocking and has to
* return NULL if no new connection is pending.
*
* Implementation of this function is MANDATORY if server functionality is required.
*
* NOTE: The behaviour of this function changed with version 0.8!
*
* \param self server socket instance
*
* \return handle of the new connection socket or NULL if no new connection is available
*/
Socket
ServerSocket_accept(ServerSocket self);
/**
* \brief set the maximum number of pending connection in the queue
*
* Implementation of this function is OPTIONAL.
*
* \param self the server socket instance
* \param backlog the number of pending connections in the queue
*
*/
void
ServerSocket_setBacklog(ServerSocket self, int backlog);
/**
* \brief destroy a server socket instance
*
* Free all resources allocated by this server socket instance.
*
* Implementation of this function is MANDATORY if server functionality is required.
*
* \param self server socket instance
*/
void
ServerSocket_destroy(ServerSocket self);
/**
* \brief create a TCP client socket
*
* Implementation of this function is MANDATORY if client functionality is required.
*
* \return a new client socket instance.
*/
Socket
TcpSocket_create(void);
/**
* \brief set the timeout to establish a new connection
*
* \param self the client socket instance
* \param timeoutInMs the timeout in ms
*/
void
Socket_setConnectTimeout(Socket self, uint32_t timeoutInMs);
/**
* \brief connect to a server
*
* Connect to a server application identified by the address and port parameter.
*
* The "address" parameter may either be a hostname or an IP address. The IP address
* has to be provided as a C string (e.g. "10.0.2.1").
*
* Implementation of this function is MANDATORY if client functionality is required.
*
* NOTE: return type changed from int to bool with version 0.8
*
* \param self the client socket instance
* \param address the IP address or hostname as C string
* \param port the TCP port of the application to connect to
*
* \return true if the connection was established successfully, false otherwise
*/
bool
Socket_connect(Socket self, const char* address, int port);
/**
* \brief read from socket to local buffer (non-blocking)
*
* The function shall return immediately if no data is available. In this case
* the function returns 0. If an error happens the function shall return -1.
*
* Implementation of this function is MANDATORY
*
* NOTE: The behaviour of this function changed with version 0.8!
*
* \param self the client, connection or server socket instance
* \param buf the buffer where the read bytes are copied to
* \param size the maximum number of bytes to read (size of the provided buffer)
*
* \return the number of bytes read or -1 if an error occurred
*/
int
Socket_read(Socket self, uint8_t* buf, int size);
/**
* \brief send a message through the socket
*
* Implementation of this function is MANDATORY
*
* \param self client, connection or server socket instance
*
* \return number of bytes transmitted of -1 in case of an error
*/
int
Socket_write(Socket self, uint8_t* buf, int size);
/**
* \brief Get the address of the peer application (IP address and port number)
*
* The peer address has to be returned as
*
* Implementation of this function is MANDATORY until version 0.9.5
*
* \deprecated starting from version 0.9.5 library uses Socket_getPeerAddressStatic
*
* \param self the client, connection or server socket instance
*
* \return the IP address and port number as strings separated by the ':' character.
*/
char*
Socket_getPeerAddress(Socket self);
/**
* \brief Get the address of the peer application (IP address and port number)
*
* The peer address has to be returned as
*
* Implementation of this function is MANDATORY
*
* \param self the client, connection or server socket instance
* \param peerAddressString a string to store the peer address (the string should have space
* for at least 60 characters)
*
* \return the IP address and port number as strings separated by the ':' character. If the
* address is an IPv6 address the IP part is encapsulated in square brackets.
*/
char*
Socket_getPeerAddressStatic(Socket self, char* peerAddressString);
/**
* \brief destroy a socket (close the socket if a connection is established)
*
* This function shall close the connection (if one is established) and free all
* resources allocated by the socket.
*
* Implementation of this function is MANDATORY
*
* \param self the client, connection or server socket instance
*/
void
Socket_destroy(Socket self);
/*! @} */
/*! @} */
#ifdef __cplusplus
}
#endif
#endif /* SOCKET_HAL_H_ */