FreeCalypso > hg > fc-magnetite

comparison src/condat3/com/include/socket_api.h @ 18:c8bd5a927942

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/condat3: import of "condat" tree from TCS3.2, pruned
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 27 Sep 2016 21:25:36 +0000
parents
children
comparison
equal deleted inserted replaced
17:6323e661f2ed 18:c8bd5a927942
1 /*
2 +------------------------------------------------------------------------------
3 | File: socket.h
4 +------------------------------------------------------------------------------
5 | Copyright 2002 Texas Instruments Berlin, AG
6 | All rights reserved.
7 |
8 | This file is confidential and a trade secret of Texas
9 | Instruments Berlin, AG
10 | The receipt of or possession of this file does not convey
11 | any rights to reproduce or disclose its contents or to
12 | manufacture, use, or sell anything it may describe, in
13 | whole, or in part, without the specific written consent of
14 | Texas Instruments Berlin, AG.
15 +-----------------------------------------------------------------------------
16 | Purpose : This file implements the socket specific definitions to be used by applications in order to
17 | set up a connection(GPRS or CSD) or create sockets for data receiption.
18 | For a description of the socket API read g23m\condat\doc\8462_601.doc
19 +-----------------------------------------------------------------------------
20 */
21
22 #ifndef __SOCKET_H__
23 #define __SOCKET_H__
24
25 #include "typedefs.h"
26 #include "vsi.h"
27 #include "gsm.h"
28 #include "prim.h" // to get the DCM defines
29
30
31 /***************** Defines added for TCPIP testing with the application. ***********/
32
33 /*
34 * Value constants for VAL_bearer_select
35 */
36 #define DCM_SOCK_BEARER_ANY (0x1) /* DCM will decide which connection type to be used */
37 #define DCM_SOCK_BEARER_GPRS (0x2) /* Use a GPRS context as bearer, DCM will decide which GPRS settings to be used */
38 #define DCM_SOCK_BEARER_GSM (0x3) /* Use GSM data connection as bearer DCM will decide which GSM settings to be used */
39 #define DCM_SOCK_BEARER_USE_PROFILE (0x4) /* Use a specific data account for this connection */
40 #define DCM_SOCK_BEARER_AS_SPECIFIED (0x5) /* Use the data account information which is which is delivered within this signal */
41
42 /*
43 * Value constants for VAL_authtype
44 */
45 #define DCM_SOCK_AUTH_PAP (0x1) /* PAP authentification protocol */
46 #define DCM_SOCK_AUTH_CHAP (0x2) /* CHAP authentification protocol !!! NOT SUPPORTED */
47 #define DCM_SOCK_AUTH_NO (0x3) /* No authentication */
48
49 /*
50 * user defined constants
51 */
52 #define CDCM_APN_MAX_LEN (0x64)
53 #define CDCM_PHONE_NR_LEN (0x54)
54 #define CDCM_USER_MAX_LEN (0x19)
55 #define CDCM_PASSWORD_MAX_LEN (0x19)
56
57 /************************************************************************************/
58
59 /*
60 * Maximum length of the full-qualified domain name of an Internet host
61 */
62 #define SOCK_MAXHOSTNAMELEN 255
63
64 /* Maximum length (in octets) of a GPRS Access Point Name (APN). */
65 #define SOCK_MAX_APN_LEN CDCM_APN_MAX_LEN
66
67 /* Maximum length (in octets) of a telephone number. */
68 #define SOCK_MAX_PHONENUM_LEN CDCM_PHONE_NR_LEN
69
70 /* Maximum length (in octets) of a user id. */
71 #define SOCK_MAX_USERID_LEN CDCM_USER_MAX_LEN
72
73 /* Maximum length (in octets) of a user password. */
74 #define SOCK_MAX_PASSWORD_LEN CDCM_PASSWORD_MAX_LEN
75
76 /*
77 * Type of an IP protocol
78 * The values of this type are used as the 'ipproto' argument when creating
79 * a socket to specify if a UDP socket or a TCP socket shall be created.
80 */
81 typedef enum {
82 SOCK_IPPROTO_TCP = 6,
83 SOCK_IPPROTO_UDP = 17
84 } T_SOCK_IPPROTO;
85
86
87 /*
88 * Type of a socket descriptor
89 */
90 typedef unsigned long T_SOCK_SOCKET;
91
92 /*
93 * Type of an API instance
94 */
95 typedef unsigned long T_SOCK_API_INSTANCE;
96
97 /*
98 * Type of an IP version 4 addresses in network byte order
99 */
100 typedef unsigned long T_SOCK_IPADDR;
101
102 #define SOCK_IPADDR_ANY (T_SOCK_IPADDR)0 /* Unspecified IP address */
103
104 /*
105 * UDP or TCP port number in network byte order
106 */
107 typedef unsigned short T_SOCK_PORT;
108
109 #define SOCK_PORT_ANY (T_SOCK_PORT)0 /* Unspecified port number */
110
111 /*
112 * Convert U32 value from host byte order to network byte order
113 */
114 #define SOCK_HTONL( x ) \
115 ((U32)((((U32)( x ) & 0x000000ffU) << 24) | \
116 (((U32)( x ) & 0x0000ff00U) << 8) | \
117 (((U32)( x ) & 0x00ff0000U) >> 8) | \
118 (((U32)( x ) & 0xff000000U) >> 24)))
119
120 /*
121 * Convert U16 value from host byte order to network byte order
122 */
123 #define SOCK_HTONS( x ) \
124 ((U16)((((U16)( x ) & 0x00ff) << 8) | \
125 (((U16)( x ) & 0xff00) >> 8)))
126
127 /*
128 * Convert U32 value from network byte order to host byte order
129 */
130 #define SOCK_NTOHL( x ) \
131 ((U32)((((U32)( x ) & 0x000000ffU) << 24) | \
132 (((U32)( x ) & 0x0000ff00U) << 8) | \
133 (((U32)( x ) & 0x00ff0000U) >> 8) | \
134 (((U32)( x ) & 0xff000000U) >> 24)))
135
136 /*
137 * Convert U16 value from network byte order to host byte order
138 */
139 #define SOCK_NTOHS( x ) \
140 ((U16)((((U16)( x ) & 0x00ff) << 8) | \
141 (((U16)( x ) & 0xff00) >> 8)))
142
143 /*
144 * Construct IP address in network byte order from single octets.
145 */
146 #define SOCK_MK_IPADDR( a, b, c, d ) \
147 ((T_SOCK_IPADDR)((a << 24) | (b << 16) | (c << 8) | d))
148
149 /*
150 * Type of a Socket API event
151 */
152 typedef enum {
153 SOCK_CREATE_CNF = 1, /* Result event of sock_create() */
154 SOCK_CLOSE_CNF = 2, /* Result event of sock_close() */
155 SOCK_BIND_CNF = 3, /* Result event of sock_bind() */
156 SOCK_LISTEN_CNF = 4, /* Result event of sock_listen() */
157 SOCK_CONNECT_CNF = 5, /* Result event of sock_connect() */
158 SOCK_SOCKNAME_CNF = 6, /* Result event of sock_getsockname() */
159 SOCK_PEERNAME_CNF = 7, /* Result event of sock_getpeername() */
160 SOCK_HOSTINFO_CNF = 8, /* Result event of sock_gethostbyname() or sock_gethostbyaddr() */
161 SOCK_MTU_SIZE_CNF = 9, /* Result event of sock_get_mtu_size() */
162 SOCK_RECV_IND = 10, /* Network event: data has been received */
163 SOCK_CONNECT_IND = 11, /* Network event: an incoming connection has been accepted. */
164 SOCK_CONN_CLOSED_IND = 12, /* Network event: connection has been closed by the remote peer */
165 SOCK_ERROR_IND = 13, /* Network event: an asynchronous error has occurred */
166 SOCK_FLOW_READY_IND = 14, /* Flow control: the API is ready to send data again */
167
168 SOCK_OPEN_BEARER_CNF, // Result Event of sock_open_bearer()
169 SOCK_CLOSE_BEARER_CNF, // Result event of sock_close_bearer()
170 SOCK_BEARER_INFO_CNF, // Result event of sock_bearer_info()
171 SOCK_BAERER_CLOSED_IND // The bearer connection has been closed
172 } T_SOCK_EVENTTYPE;
173
174 /*
175 * Result codes of the API functions to indicate success or an error condition.
176 * This type is used as the result code of the function and as the result value
177 * in the associated event. It is also used for the error codes of a
178 * 'SOCK_ERROR_IND' event
179 */
180 typedef enum {
181 SOCK_RESULT_OK = 0, /* No problem detected. a corresponding primitive has been sent to the TCP/IP entity */
182 SOCK_RESULT_INVALID_PARAMETER = 1, /* A parameter given to the function is invalid */
183 SOCK_RESULT_INTERNAL_ERROR = 2, /* An internal error has happened */
184 SOCK_RESULT_ADDR_IN_USE = 3, /* The address or port is already in use */
185 SOCK_RESULT_OUT_OF_MEMORY = 4, /* There is not enough memory to fulfill the request */
186 SOCK_RESULT_NOT_SUPPORTED = 5, /* The socket is not of a type that can support this operation */
187 SOCK_RESULT_UNREACHABLE = 6, /* The specified host cannot be reached */
188 SOCK_RESULT_CONN_REFUSED = 7, /* The connection to the specified address was refused by the remote host */
189 SOCK_RESULT_TIMEOUT = 8, /* The connection attempt timed out without establishing a connection */
190 SOCK_RESULT_IS_CONNECTED = 9, /* The request could not be fulfilled because the socket is already connected */
191 SOCK_RESULT_HOST_NOT_FOUND = 10, /* The specified host could not be found in the DNS */
192 SOCK_RESULT_DNS_TEMP_ERROR = 11, /* A temporary DNS error has occurred. Retrying the query may be successful */
193 SOCK_RESULT_DNS_PERM_ERROR = 12, /* A permanent DNS error has occurred */
194 SOCK_RESULT_NO_IPADDR = 13, /* The specified name has been found in the DNS, but no IP address is available */
195 SOCK_RESULT_NOT_CONNECTED = 14, /* The socket has not been connected yet */
196 SOCK_RESULT_MSG_TOO_BIG = 15, /* The size of the data buffer is too large for a UDP socket */
197 SOCK_RESULT_CONN_RESET = 16, /* The connection has been reset by the remote peer */
198 SOCK_RESULT_CONN_ABORTED = 17, /* The connection was aborted due to timeout or some other error condition */
199 SOCK_RESULT_NO_BUFSPACE = 18, /* Sending failed temporarily because the space to buffer the message was exhausted. */
200 SOCK_RESULT_NETWORK_LOST, // As a result code: The operation failed because TCP/IP's bearer connection has been disconnected.As an asynchronous event code: The bearer connection has been closed.
201 SOCK_RESULT_NOT_READY, // The operation failed because the bearer connection has not been opened.
202 SOCK_RESULT_BEARER_NOT_READY, // The bearer connection could not be opened because the mobile is not yet completely attached to the network. A retry at a later time may be successful.
203 SOCK_RESULT_IN_PROGRESS, // The operation failed because a similar operation is already in progress.
204 SOCK_RESULT_BEARER_ACTIVE// The operation failed because a bearer connection is already open.
205 } T_SOCK_RESULT;
206
207
208 /* Type of the bearer_select parameter of sock_open_bearer(), used to select the
209 * type of the bearer connection to be opened by the Data Connection Manager
210 * (DCM), and of the bearer_type field of the T_SOCK_BEARER_INFO struct.
211 */
212 typedef enum {
213 SOCK_BEARER_ANY = DCM_SOCK_BEARER_ANY,
214 SOCK_BEARER_GPRS = DCM_SOCK_BEARER_GPRS,
215 SOCK_BEARER_GSM = DCM_SOCK_BEARER_GSM,
216 SOCK_BEARER_USE_PROFILE = DCM_SOCK_BEARER_USE_PROFILE,
217 SOCK_BEARER_AS_SPECIFIED = DCM_SOCK_BEARER_AS_SPECIFIED
218 } T_SOCK_BEARER_TYPE;
219
220 // FST: ?????
221 typedef enum {
222 SOCK_AUTH_PAP = DCM_SOCK_AUTH_PAP,
223 SOCK_AUTH_CHAP = DCM_SOCK_AUTH_CHAP,
224 SOCK_AUTH_NO= DCM_SOCK_AUTH_NO
225 } T_SOCK_AUTHTYPE;
226
227 /*
228 * Type of the generic event data structure passed
229 * to the callback function on an event.
230 * The actual event structure may be bigger(depending on its type),
231 * but it will contain these fields at the beginning
232 */
233 typedef struct {
234 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
235 T_SOCK_RESULT result; /* Result code of the operation */
236 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
237 } T_SOCK_EVENTSTRUCT;
238
239 /*
240 * Pointer to the callback function specified by the application
241 */
242 typedef void (*T_SOCK_CALLBACK)(T_SOCK_EVENTSTRUCT* event, void *context);
243
244 /* System wide handle of a bearer connection.
245 * Variables of this type are used as handles to identify a bearer connection.
246 * !! NOT NEEDED FOR CURRENT IMPLEMENTATION ONLY MENTIONED FOR FUTURE SUPPOSE.!!
247 */
248 typedef U16 T_SOCK_BEARER_HANDLE;
249
250 typedef struct {
251 T_SOCK_BEARER_HANDLE bearer_handle;
252 T_HANDLE app_handle;
253 T_SOCK_BEARER_TYPE bearer_type;
254 BOOL apn_valid;
255 char apn[SOCK_MAX_APN_LEN+1];
256 BOOL phone_nr_valid;
257 char phone_nr[SOCK_MAX_PHONENUM_LEN+1];
258 BOOL user_id_valid;
259 char user_id[SOCK_MAX_USERID_LEN+1];
260 BOOL password_valid;
261 char password[SOCK_MAX_PASSWORD_LEN+1];
262 int cid;
263 T_SOCK_IPADDR ip_address;
264 T_SOCK_IPADDR dns1;
265 T_SOCK_IPADDR dns2;
266 T_SOCK_IPADDR gateway;
267 T_SOCK_AUTHTYPE authtype;
268 BOOL data_compr;
269 BOOL header_comp;
270 int precedence;
271 int delay;
272 int reliability;
273 int peak_throughput;
274 int mean_througput;
275 BOOL shareable;
276 } T_SOCK_BEARER_INFO;
277
278 /* ========================================================================== */
279 /* ============================== Result Events from TCPIP ================= */
280
281 typedef struct {
282 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
283 T_SOCK_RESULT result; /* Result code of the operation */
284 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
285 T_SOCK_BEARER_HANDLE bearer_handle;
286 } T_SOCK_OPEN_BEARER_CNF;
287
288 typedef T_SOCK_EVENTSTRUCT T_SOCK_CLOSE_BEARER_CNF;
289
290 typedef struct {
291 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
292 T_SOCK_RESULT result; /* Result code of the operation */
293 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
294 T_SOCK_BEARER_INFO bearer_params;
295 } T_SOCK_BEARER_INFO_CNF;
296
297 typedef struct {
298 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
299 T_SOCK_RESULT result; /* Result code of the operation */
300 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
301 U32 dcm_error; /* The parameter contains errors received from
302 * PS (ETSI Spec 07.07) */
303 } T_SOCK_BAERER_CLOSED_IND;
304
305 typedef struct {
306 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
307 T_SOCK_RESULT result; /* Result code of the operation */
308 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
309 } T_SOCK_CREATE_CNF;
310
311 typedef T_SOCK_EVENTSTRUCT T_SOCK_CLOSE_CNF;
312 typedef T_SOCK_EVENTSTRUCT T_SOCK_BIND_CNF;
313 typedef T_SOCK_EVENTSTRUCT T_SOCK_LISTEN_CNF;
314 typedef T_SOCK_EVENTSTRUCT T_SOCK_CONNECT_CNF;
315
316 typedef struct {
317 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
318 T_SOCK_RESULT result; /* Result code of the operation */
319 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
320 T_SOCK_IPADDR ipaddr; /* The local IP address of the socket */
321 T_SOCK_PORT port; /* The local port number of the socket */
322 } T_SOCK_SOCKNAME_CNF;
323
324 typedef T_SOCK_SOCKNAME_CNF T_SOCK_PEERNAME_CNF;
325
326 typedef struct {
327 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
328 T_SOCK_RESULT result; /* Result code of the operation */
329 T_SOCK_SOCKET socket; /* unused */
330 char hostname[SOCK_MAXHOSTNAMELEN+1]; /* The name of the host as
331 a zero-terminated string */
332 T_SOCK_IPADDR ipaddr; /* The local IP address of the socket */
333 } T_SOCK_HOSTINFO_CNF;
334
335 typedef struct {
336 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
337 T_SOCK_RESULT result; /* Result code of the operation */
338 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
339 U16 mtu_size; /* MTU size */
340 } T_SOCK_MTU_SIZE_CNF;
341
342 typedef struct {
343 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
344 T_SOCK_RESULT result; /* Result code of the operation */
345 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
346 U32 data_length; /* Length of the data portion received. */
347 char *data_buffer; /* Pointer to the data received. The application
348 shall free this data buffer after use. */
349 } T_SOCK_RECV_IND;
350
351
352 typedef struct {
353 T_SOCK_EVENTTYPE event_type; /* Type of the event. */
354 T_SOCK_RESULT result; /* Result code of the operation */
355 T_SOCK_SOCKET socket; /* Socket for which the event occurred */
356 T_SOCK_SOCKET new_socket; /* New socket allocated for the connection. */
357 T_SOCK_IPADDR peer_ipaddr; /* IP address of the remote peer. */
358 T_SOCK_PORT peer_port; /* Port number on the remote side. */
359 } T_SOCK_CONNECT_IND;
360
361 typedef T_SOCK_EVENTSTRUCT T_SOCK_CONN_CLOSED_IND;
362 typedef T_SOCK_EVENTSTRUCT T_SOCK_ERROR_IND;
363 typedef T_SOCK_EVENTSTRUCT T_SOCK_FLOW_READY_IND;
364
365
366
367 /* ========================================================================== */
368 /* ================== Prototypes of socket API ============================== */
369
370
371 /* ******************* API administrative functions ************************* */
372
373 /*------------------------------------------------------------------------------
374 Function : sock_api_initialize
375 Parameter : - T_SOCK_API_INSTANCE * :
376 'The function returns an API instance value. The value is needed
377 for several API functions.'
378 - T_HANDLE :
379 'Application task handle as passed to pei_init()'
380 - char* :
381 'Name of the application entity as used with vsi_c_open().'
382 Return : The function returns TRUE if the initialization was successful.
383 Description : Initializes the socket interface API.
384 ------------------------------------------------------------------------------*/
385 BOOL sock_api_initialize(T_SOCK_API_INSTANCE *api_instance,
386 T_HANDLE app_handle,
387 char* app_name);
388
389
390 /*------------------------------------------------------------------------------
391 Function : sock_api_deinitialize
392 Parameter : - T_SOCK_API_INSTANCE :
393 'API instance value.'
394 Return : None
395 Description : Deinitializes the socket interface API. The function releases
396 all associated memory.
397 ------------------------------------------------------------------------------*/
398 void sock_api_deinitialize(T_SOCK_API_INSTANCE api_instance);
399
400
401 /*------------------------------------------------------------------------------
402 Function : sock_api_handles_primitive
403 Parameter : - T_SOCK_API_INSTANCE: API instance value
404 - T_PRIM: Pointer to primitive received from
405 the primitive queue'
406 Return : The function returns TRUE if the primitive has been handled by
407 this function.In this case the application should not do
408 anything else with the primitive and should not call PFREE()
409 to free the memory block used for the primitive.
410 The function returns FALSE if the primitive has not been
411 handled by this function. In this case the application should
412 process the primitive as usual.
413 Description : Handles primitives for the socket API.
414 To free the application from the handling of the event
415 primitives sent by the TCP/IP entity, the Socket API provides
416 this function that checks if a primitive is to be handled by
417 the Socket API and if it is, handles it. The application is
418 supposed to call it immediately after receiving a primitive.
419 If the primitive is meant for the Socket API, it is handled by
420 this function. This will in most cases include calling the
421 callback function supplied by the application to deliver an
422 event. If the primitive is not meant for the Socket API,
423 no action is taken.
424 It is recommended to call this function early in the
425 application entity's pei_primitive() function.
426 ------------------------------------------------------------------------------*/
427 BOOL sock_api_handles_primitive(T_SOCK_API_INSTANCE api_instance,
428 T_PRIM *prim);
429
430
431 /* ******************* Bearer related functions ***************************** */
432
433 /*------------------------------------------------------------------------------
434 Function : sock_open_bearer()
435 Parameter : - T_SOCK_API_INSTANCE: API instance value
436 - T_SOCK_BEARER_TYPE : CSD or GPRS
437 - int: Number of the selected profile with a bearer
438 selection of SOCK_BEARER_USE_PROFILE.
439 Unused in other cases.
440 - T_SOCK_BEARER_INFO: requested parameters of the bearer connection
441 - T_SOCK_CALLBACK: callback function to be called for return events.
442 - void*: An arbitrary pointer to be passed to the
443 callback function when it is called
444 Return : T_SOCK_RESULT indicates successor a problem that happend
445 Return Event : T_SOCK_OPEN_BEARER_CNF
446 Description : Opens a CSD or GPRS connection for use with TCP/IP.
447 This function a bearer connection for use with TCP/IP. It must be
448 called after sock_api_initialize() and before any other
449 TCP/IP-related functions.
450 ------------------------------------------------------------------------------*/
451 T_SOCK_RESULT sock_open_bearer(T_SOCK_API_INSTANCE api_instance,
452 T_SOCK_BEARER_TYPE bearer_select,
453 int profile_number,
454 T_SOCK_BEARER_INFO *params,
455 T_SOCK_CALLBACK sock_cb,
456 void *context);
457
458
459 /*------------------------------------------------------------------------------
460 Function : sock_close_bearer()
461 Parameter : - T_SOCK_API_INSTANCE : API instance value
462 - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
463 - T_SOCK_CALLBACK: Callback function to be called for return events.
464 - void*: An arbitrary pointer to be passed to the
465 callback function when it is called
466 Return : T_SOCK_RESULT indicates successor a problem that happend
467 Return Event : T_SOCK_CLOSE_BEARER_CNF
468 Description : Close a bearer connection that has been opened with sock_open_bearer().
469 ------------------------------------------------------------------------------*/
470 T_SOCK_RESULT sock_close_bearer(T_SOCK_API_INSTANCE api_instance,
471 T_SOCK_BEARER_HANDLE bearer_handle,
472 T_SOCK_CALLBACK sock_cb,
473 void *context);
474
475
476 /*------------------------------------------------------------------------------
477 Function : sock_bearer_info()
478 Parameter : - T_SOCK_API_INSTANCE: API instance value
479 - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
480 - T_SOCK_CALLBACK: Callback function to be called for
481 return events.
482 - void*: An arbitrary pointer to be passed to the
483 callback function when it is called
484 Return : T_SOCK_RESULT
485 Return Event : T_SOCK_BEARER_INFO_CNF
486 Description : Get information about a bearer connection that has been opened
487 with sock_open_bearer().
488 ------------------------------------------------------------------------------*/
489 T_SOCK_RESULT sock_bearer_info(T_SOCK_API_INSTANCE api_instance,
490 T_SOCK_BEARER_HANDLE bearer_handle,
491 T_SOCK_CALLBACK sock_cb,
492 void *context);
493
494
495 /* ******************* Socket related functions ***************************** */
496
497 /*------------------------------------------------------------------------------
498 Function : sock_create
499 Parameter : - T_SOCK_API_INSTANCE :
500 'API instance value.'
501 - T_SOCK_IPPROTO :
502 'The protocol (UDP or TCP) to be used with this socket'
503 - T_SOCK_CALLBACK :
504 'The callback function to be called for events on this socket'
505 - void * :
506 'An arbitrary pointer to be passed to
507 the callback function when it is called'
508 Return : (T_SOCK_RESULT)
509 Return Event : 'SOCK_CREATE_CNF'
510 - T_SOCK_RESULT : Result code
511 - T_SOCK_SOCKET : The socket descriptor returned by the TCP/IP entity
512 Description : - Create a new UDP or TCP socket
513 - This function creates a socket that can subsequently be used with
514 the other Socket API functions
515 ------------------------------------------------------------------------------*/
516 T_SOCK_RESULT sock_create(T_SOCK_API_INSTANCE api_instance,
517 T_SOCK_IPPROTO ipproto,
518 T_SOCK_CALLBACK callback,
519 void *context);
520
521
522 /*------------------------------------------------------------------------------
523 Function : sock_close
524 Parameter : - T_SOCK_SOCKET :
525 'The socket descriptor to be closed'
526 Return : (T_SOCK_RESULT)
527 Return Event : 'SOCK_CLOSE_CNF'
528 - T_SOCK_RESULT : Result code
529 - T_SOCK_SOCKET : The socket descriptor to be closed
530 Description : - Close socket, shutdown connection if present
531 - This function closes a socket that has previously
532 been created with sock_create().
533 If a connection is open for this socket, it will be closed.
534 If this socket has listened for connections,
535 no further connections will be accepted
536 History : 0001 03.08.11 shkim Created
537 ------------------------------------------------------------------------------*/
538 T_SOCK_RESULT sock_close(T_SOCK_SOCKET socket);
539
540
541 /*------------------------------------------------------------------------------
542 Function : sock_bind
543 Parameter : - T_SOCK_SOCKET :
544 'The socket descriptor to be closed'
545 - T_SOCK_PORT :
546 'The port number to bind the socket to'
547 Return : (T_SOCK_RESULT)
548 Return Event : 'SOCK_BIND_CNF'
549 - T_SOCK_RESULT : Result code
550 - T_SOCK_SOCKET : The socket descriptor to be bound
551 Description : - Bind socket to a specific local port number
552 - This function binds a socket to the specified local port
553 History : 0001 03.08.11 shkim Created
554 ------------------------------------------------------------------------------*/
555 T_SOCK_RESULT sock_bind(T_SOCK_SOCKET socket,
556 T_SOCK_PORT port);
557
558
559 /*------------------------------------------------------------------------------
560 Function : sock_listen
561 Parameter : - T_SOCK_SOCKET :
562 'The socket descriptor to listen on'
563 Return : (T_SOCK_RESULT)
564 Return Event : 'SOCK_LISTEN_CNF'
565 - T_SOCK_RESULT : Result code
566 - T_SOCK_SOCKET : The socket descriptor to listen on
567 Description : - Accept TCP connections on this socket
568 - This function makes TCP/IP listen for
569 TCP connections on this socket.
570 The socket should have been bound to a specific port
571 using sock_bind() before.
572 History : 0001 03.08.11 shkim Created
573 ------------------------------------------------------------------------------*/
574 T_SOCK_RESULT sock_listen(T_SOCK_SOCKET socket);
575
576
577 /*------------------------------------------------------------------------------
578 Function : sock_connect
579 Parameter : - T_SOCK_SOCKET :
580 'The socket descriptor to connect'
581 - T_SOCK_IPADDR :
582 'The IP address to connect to'
583 - T_SOCK_PORT :
584 'The port number to connect to'
585 Return : (T_SOCK_RESULT)
586 Return Event : 'SOCK_CONNECT_CNF'
587 - T_SOCK_RESULT : Result code
588 - T_SOCK_SOCKET : The socket descriptor to connect
589 Description : - Connect the socket to a remote endpoint
590 - With TCP sockets, a TCP connection is established to
591 the specified IP address and the specified port.
592 The connection can then be used to send data using sock_send();
593 received data is indicated by a SOCK_RECV_IND event.
594 With UDP sockets, the specified IP address and port number
595 are stored with the socket;
596 subsequent UDP messages can be sent to this address
597 using sock_send();
598 only messages from this address will be received.
599 History : 0001 03.08.11 shkim Created
600 ------------------------------------------------------------------------------*/
601 T_SOCK_RESULT sock_connect(T_SOCK_SOCKET socket,
602 T_SOCK_IPADDR ipaddr,
603 T_SOCK_PORT port);
604
605
606 /*------------------------------------------------------------------------------
607 Function : sock_getsockname
608 Parameter : - T_SOCK_SOCKET :
609 'The socket descriptor to retrieve information about'
610 Return : (T_SOCK_RESULT)
611 Return Event : 'SOCK_SOCKNAME_CNF'
612 - T_SOCK_RESULT : Result code
613 - T_SOCK_SOCKET : The socket descriptor to connect
614 - T_SOCK_IPADDR : The local IP address of the socket
615 - T_SOCK_PORT : The local port number of the socket
616 Description : - Retrieve local address information
617 - The function retrieves local address information of the socket.
618 If the socket has not yet been bound to an address using sock_bind(),
619 the port number is unspecified (SOCK_PORT_ANY)
620 History : 0001 03.08.11 shkim Created
621 ------------------------------------------------------------------------------*/
622 T_SOCK_RESULT sock_getsockname(T_SOCK_SOCKET socket);
623
624
625 /*------------------------------------------------------------------------------
626 Function : sock_getpeername
627 Parameter : - T_SOCK_SOCKET :
628 'The socket descriptor to retrieve information about'
629 Return : (T_SOCK_RESULT)
630 Return Event : 'SOCK_PEERNAME_CNF'
631 - T_SOCK_RESULT : Result code
632 - T_SOCK_SOCKET : The socket descriptor to connect
633 - T_SOCK_IPADDR : The IP address of the remote peer
634 - T_SOCK_PORT : The port number at the remote peer
635 Description : - Retrieve remote address information
636 - The function retrieves address information of
637 the connection at the remote peer.
638 If the socket is not connected,
639 the IP address and port number are unspecified
640 ------------------------------------------------------------------------------*/
641 T_SOCK_RESULT sock_getpeername(T_SOCK_SOCKET socket);
642
643
644 /*------------------------------------------------------------------------------
645 Function : sock_gethostbyname
646 Parameter : - T_SOCK_API_INSTANCE :
647 'API instance value.'
648 - char * :
649 'The name of the referenced host'
650 - T_SOCK_CALLBACK :
651 'The callback function to be called for the result event'
652 - void * :
653 'An arbitrary pointer to be passed to the callback
654 function when it is called'
655 Return : (T_SOCK_RESULT)
656 Return Event : 'SOCK_HOSTINFO_CNF'
657 - T_SOCK_RESULT : Result code
658 - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the
659 host as a zero-terminated string
660 - T_SOCK_IPADDR : The IP address of the host
661 Description : - Get the IP address of a host
662 - The function queries the IP address information of
663 the specified host from the DNS.
664 Because the function is not associated to any socket,
665 a callback function and a context
666 pointer must be specified separately
667 ------------------------------------------------------------------------------*/
668 T_SOCK_RESULT sock_gethostbyname(T_SOCK_API_INSTANCE api_instance,
669 char *hostname,
670 T_SOCK_CALLBACK callback,
671 void *context);
672
673
674 /*------------------------------------------------------------------------------
675 Function : sock_gethostbyaddr
676 Parameter : - T_SOCK_API_INSTANCE :
677 'API instance value.'
678 - T_SOCK_IPADDR :
679 'The IP address of the referenced host'
680 - T_SOCK_CALLBACK :
681 'The callback function to be called for the result event'
682 - void * :
683 'An arbitrary pointer to be passed to the callback function
684 when it is called'
685 Return : (T_SOCK_RESULT)
686 Return Event : 'SOCK_HOSTINFO_CNF'
687 - T_SOCK_RESULT : Result code
688 - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the
689 host as a zero-terminated string
690 - T_SOCK_IPADDR : The IP address of the host
691 Description : - Get the name of a host
692 - The function queries the hostname for the specified
693 IP address from the DNS.
694 Because the function is not associated to any socket,
695 a callback function and a context pointer must be specified separately
696 ------------------------------------------------------------------------------*/
697 T_SOCK_RESULT sock_gethostbyaddr(T_SOCK_API_INSTANCE api_instance,
698 T_SOCK_IPADDR ipaddr,
699 T_SOCK_CALLBACK callback,
700 void *context);
701
702
703 /*------------------------------------------------------------------------------
704 Function : sock_send
705 Parameter : - T_SOCK_SOCKET :
706 'The socket to send the data on'
707 - char * :
708 'The data buffer to be sent'
709 - U16 :
710 'The length of the data buffer in bytes'
711 Return : (T_SOCK_RESULT)
712 Return Event : None
713 Description : - Send data on a socket ( TCP only )
714 - The function sends the specified data buffer over the socket.
715 The socket must be connected,
716 i. e. it must have been connected to a remote peer
717 using sock_connect() or been created when accepting
718 a connection as indicated by SOCK_SONNECT_IND.
719 Implementation note: In order to send the payload data via DTI,
720 the data must be copied into a DTI descriptor by the Socket API;
721 there is no way to avoid the copy operation without
722 putting the burden of knowing DTI-internal data
723 structures on the application.
724 It has been decided to pay the cost of the copy operation
725 in order to free the application from this responsibility
726 ------------------------------------------------------------------------------*/
727 T_SOCK_RESULT sock_send(T_SOCK_SOCKET socket,
728 char *buffer,
729 U16 buffer_length);
730
731
732 /*------------------------------------------------------------------------------
733 Function : sock_sendto
734 Parameter : - T_SOCK_SOCKET :
735 'The socket to send the data on'
736 - char * :
737 'The data buffer to be sent'
738 - U16 :
739 'The length of the data buffer'
740 - T_SOCK_IPADDR :
741 'IP address of the host to send data to'
742 - T_SOCK_PORT :
743 'Remote port to send data to'
744 Return : (T_SOCK_RESULT)
745 Return Event : None
746 Description : - Send data on a socket( UDP only )
747 - The function sends the specified data buffer
748 over the socket to the specified address. The socket must be
749 a UDP socket.
750 Implementation note: In order to send the payload data via DTI,
751 the data must be copied into a DTI descriptor by the Socket API;
752 there is no way to avoid the copy operation without putting
753 the burden of knowing DTI-internal data structures on
754 the application. It has been decided to pay the cost of
755 the copy operation in order to free the application from
756 this responsibility
757 ------------------------------------------------------------------------------*/
758 T_SOCK_RESULT sock_sendto(T_SOCK_SOCKET socket,
759 char *buffer,
760 U16 buffer_length,
761 T_SOCK_IPADDR ipaddr,
762 T_SOCK_PORT port);
763
764
765 /*------------------------------------------------------------------------------------
766 Function : sock_set_callback
767 Parameter : - T_SOCK_SOCKET :
768 'Socket to set callback and context for'
769 - T_SOCK_CALLBACK :
770 'New callback function for the socket'
771 - void * :
772 'New context pointer for the socket'
773 Return : (T_SOCK_RESULT)
774 Return Event : None
775 Description : - Set a new callback function and context pointer for the socket
776 - The function defines a new callback function and a new context
777 pointer for the socket. All socket events after this call will be
778 delivered using the new callback function and the new context
779 pointer
780 ------------------------------------------------------------------------------*/
781 T_SOCK_RESULT sock_set_callback(T_SOCK_SOCKET socket,
782 T_SOCK_CALLBACK callback,
783 void *context);
784
785
786 /*------------------------------------------------------------------------------
787 Function : sock_get_callback
788 Parameter : - T_SOCK_SOCKET :
789 'Socket to get callback and context from'
790 - T_SOCK_CALLBACK * :
791 'Return callback function pointer for the socket'
792 - void ** :
793 'Return context pointer for the socket'
794 Return : (T_SOCK_RESULT)
795 Return Event : None
796 Description : - Get callback function pointer and context pointer for the socket
797 - The function returns callback function pointer and context pointer
798 for the socket.
799 pointer
800 ------------------------------------------------------------------------------*/
801 T_SOCK_RESULT sock_get_callback(T_SOCK_SOCKET socket,
802 T_SOCK_CALLBACK *callback_p,
803 void **context_p);
804
805
806 /*------------------------------------------------------------------------------
807 Function : sock_flow_xoff
808 Parameter : - T_SOCK_SOCKET :
809 'Socket to switch to "xoff" status'
810 Return : (T_SOCK_RESULT)
811 Return Event : None
812 Description : - Flow control: make TCP/IP stop sending data
813 - This function makes the Socket API stop TCP/IP sending data.
814 If TCP/IP has already been stopped, the function has no effect.
815 History : 0001 03.08.11 shkim Created
816 0002 03.09.12 STW T_SOCK_RESULT added
817 ------------------------------------------------------------------------------*/
818 T_SOCK_RESULT sock_flow_xoff(T_SOCK_SOCKET socket);
819
820
821 /*------------------------------------------------------------------------------
822 Function : sock_flow_xon
823 Parameter : - T_SOCK_SOCKET :
824 'Socket to switch to "xon" status'
825 Return : (T_SOCK_RESULT)
826 Return Event : None
827 Description : - Flow control: make TCP/IP resume sending data
828 - This function makes TCP/IP resume sending data.
829 If TCP/IP has not been stopped, the function has no effect
830 History : 0001 03.08.11 shkim Created
831 0002 03.09.12 STW T_SOCK_RESULT added
832 ------------------------------------------------------------------------------*/
833 T_SOCK_RESULT sock_flow_xon(T_SOCK_SOCKET socket);
834
835
836 /*------------------------------------------------------------------------------
837 Function : sock_get_mtu_size
838 Parameter : - T_SOCK_SOCKET :
839 'Socket to get MTU size from'
840 Return : (T_SOCK_RESULT)
841 Return Event : 'SOCK_MTU_SIZE_CNF'
842 - T_SOCK_RESULT : Result code
843 - T_SOCK_SOCKET : The socket descriptor (unused).
844 - U16 : MTU size
845 Description : - Get MTU size of network connection
846 - The function retrieves the size of
847 the Maximum Transfer Unit(MTU) of the network connection.
848 History : 0001 03.08.11 shkim Created
849 0002 03.09.12 STW T_SOCK_SOCKET added
850 ------------------------------------------------------------------------------*/
851 T_SOCK_RESULT sock_get_mtu_size(T_SOCK_SOCKET socket);
852
853
854 #endif /* __SOCKET_H__ */