FreeCalypso > hg > fc-magnetite

comparison src/condat2/com/include/socket_api.h @ 3:93999a60b835

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