PageRenderTime 24ms CodeModel.GetById 2ms app.highlight 15ms RepoModel.GetById 1ms app.codeStats 1ms

/peek-build/m23/g23m/condat/com/include/socket_api.h

https://bitbucket.org/C0deMaver1ck/peeklinux
C++ Header | 854 lines | 269 code | 103 blank | 482 comment | 0 complexity | c31a41bb71f29e20b6bd3c89513bf047 MD5 | raw file
  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 */
 81typedef 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 */
 90typedef unsigned long       T_SOCK_SOCKET;
 91
 92/*
 93 * Type of an API instance
 94 */
 95typedef unsigned long       T_SOCK_API_INSTANCE;
 96
 97/*
 98 * Type of an IP version 4 addresses in network byte order
 99 */
100typedef 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 */
107typedef 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 */
152typedef 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 */
180typedef 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 */
212typedef 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: ?????
221typedef 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 */
233typedef 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 */
242typedef 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 */
248typedef U16 T_SOCK_BEARER_HANDLE;
249
250typedef 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
281typedef 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
288typedef T_SOCK_EVENTSTRUCT T_SOCK_CLOSE_BEARER_CNF;
289
290typedef 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
297typedef 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
305typedef 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
311typedef T_SOCK_EVENTSTRUCT      T_SOCK_CLOSE_CNF;
312typedef T_SOCK_EVENTSTRUCT      T_SOCK_BIND_CNF;
313typedef T_SOCK_EVENTSTRUCT      T_SOCK_LISTEN_CNF;
314typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONNECT_CNF;
315
316typedef 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
324typedef T_SOCK_SOCKNAME_CNF   T_SOCK_PEERNAME_CNF;
325
326typedef 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
335typedef 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
342typedef 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
352typedef 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
361typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONN_CLOSED_IND;
362typedef T_SOCK_EVENTSTRUCT      T_SOCK_ERROR_IND;
363typedef 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------------------------------------------------------------------------------*/
385BOOL 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------------------------------------------------------------------------------*/
398void 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------------------------------------------------------------------------------*/
427BOOL 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------------------------------------------------------------------------------*/
451T_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------------------------------------------------------------------------------*/
470T_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------------------------------------------------------------------------------*/
489T_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------------------------------------------------------------------------------*/
516T_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------------------------------------------------------------------------------*/
538T_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------------------------------------------------------------------------------*/
555T_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------------------------------------------------------------------------------*/
574T_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------------------------------------------------------------------------------*/
601T_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------------------------------------------------------------------------------*/
622T_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------------------------------------------------------------------------------*/
641T_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------------------------------------------------------------------------------*/
668T_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------------------------------------------------------------------------------*/
697T_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------------------------------------------------------------------------------*/
727T_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------------------------------------------------------------------------------*/
758T_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------------------------------------------------------------------------------*/
781T_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------------------------------------------------------------------------------*/
801T_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------------------------------------------------------------------------------*/
818T_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------------------------------------------------------------------------------*/
833T_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------------------------------------------------------------------------------*/
851T_SOCK_RESULT sock_get_mtu_size(T_SOCK_SOCKET socket);
852
853
854#endif  /* __SOCKET_H__ */