diff gsm-fw/include/condat/socket_api.h @ 662:a712c95b60c1

gsm-fw/include/condat: import of TI's g23m/condat/com/include custom.h, pwr.h and rtc.h taken from TCS211 version, the others are the versions from LoCosto
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Sun, 28 Sep 2014 01:14:48 +0000
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gsm-fw/include/condat/socket_api.h	Sun Sep 28 01:14:48 2014 +0000
@@ -0,0 +1,854 @@
+/* 
++------------------------------------------------------------------------------
+|  File:       socket.h
++------------------------------------------------------------------------------
+|  Copyright 2002 Texas Instruments Berlin, AG 
+|                 All rights reserved. 
+| 
+|                 This file is confidential and a trade secret of Texas 
+|                 Instruments Berlin, AG 
+|                 The receipt of or possession of this file does not convey 
+|                 any rights to reproduce or disclose its contents or to 
+|                 manufacture, use, or sell anything it may describe, in 
+|                 whole, or in part, without the specific written consent of 
+|                 Texas Instruments Berlin, AG. 
++----------------------------------------------------------------------------- 
+|  Purpose :  This file implements the socket specific definitions to be used by applications in order to
+|             set up a connection(GPRS or CSD) or create sockets for data receiption.
+|             For a description of the socket API read g23m\condat\doc\8462_601.doc
++----------------------------------------------------------------------------- 
+*/ 
+
+#ifndef __SOCKET_H__
+#define __SOCKET_H__
+
+#include "typedefs.h"
+#include "vsi.h"
+#include "gsm.h"
+#include "prim.h" // to get the DCM defines
+
+
+/***************** Defines added for TCPIP testing with the application. ***********/
+
+/*
+ * Value constants for VAL_bearer_select
+ */
+#define DCM_SOCK_BEARER_ANY            (0x1)      /* DCM will decide which connection type to be used */
+#define DCM_SOCK_BEARER_GPRS           (0x2)      /* Use a GPRS context as bearer, DCM will decide which GPRS settings to be used */
+#define DCM_SOCK_BEARER_GSM            (0x3)      /* Use GSM data connection as bearer DCM will decide which GSM settings to be used */
+#define DCM_SOCK_BEARER_USE_PROFILE    (0x4)      /* Use a specific data account for this connection */
+#define DCM_SOCK_BEARER_AS_SPECIFIED   (0x5)      /* Use the data account information which is which is delivered within this signal */
+
+/*
+ * Value constants for VAL_authtype
+ */
+#define DCM_SOCK_AUTH_PAP              (0x1)      /* PAP authentification protocol  */
+#define DCM_SOCK_AUTH_CHAP             (0x2)      /* CHAP authentification protocol !!! NOT SUPPORTED */
+#define DCM_SOCK_AUTH_NO               (0x3)      /* No authentication              */
+
+/*
+ * user defined constants
+ */
+#define CDCM_APN_MAX_LEN               (0x64)     
+#define CDCM_PHONE_NR_LEN              (0x54) 
+#define CDCM_USER_MAX_LEN              (0x19)     
+#define CDCM_PASSWORD_MAX_LEN          (0x19)     
+
+/************************************************************************************/
+
+/*
+ * Maximum length of the full-qualified domain name of an Internet host
+ */
+#define SOCK_MAXHOSTNAMELEN 255
+
+/* Maximum length (in octets) of a GPRS Access Point Name (APN). */
+#define SOCK_MAX_APN_LEN CDCM_APN_MAX_LEN
+
+/* Maximum length (in octets) of a telephone number. */
+#define SOCK_MAX_PHONENUM_LEN CDCM_PHONE_NR_LEN
+
+/* Maximum length (in octets) of a user id. */
+#define SOCK_MAX_USERID_LEN CDCM_USER_MAX_LEN
+
+/* Maximum length (in octets) of a user password. */
+#define SOCK_MAX_PASSWORD_LEN CDCM_PASSWORD_MAX_LEN
+
+/*
+ * Type of an IP protocol
+ * The values of this type are used as the 'ipproto' argument when creating
+ * a socket to specify if a UDP socket or a TCP socket shall be created.
+ */
+typedef enum {
+  SOCK_IPPROTO_TCP =  6,
+  SOCK_IPPROTO_UDP = 17
+} T_SOCK_IPPROTO;
+
+
+/*
+ * Type of a socket descriptor
+ */
+typedef unsigned long       T_SOCK_SOCKET;
+
+/*
+ * Type of an API instance
+ */
+typedef unsigned long       T_SOCK_API_INSTANCE;
+
+/*
+ * Type of an IP version 4 addresses in network byte order
+ */
+typedef unsigned long       T_SOCK_IPADDR;
+
+#define SOCK_IPADDR_ANY    (T_SOCK_IPADDR)0  /*  Unspecified IP address */
+
+/*
+ * UDP or TCP port number in network byte order
+ */
+typedef unsigned short     T_SOCK_PORT;
+
+#define SOCK_PORT_ANY      (T_SOCK_PORT)0    /* Unspecified port number */
+
+/*
+ * Convert U32 value from host byte order to network byte order
+ */
+#define SOCK_HTONL( x )  \
+        ((U32)((((U32)( x )  & 0x000000ffU) << 24) | \
+               (((U32)( x )  & 0x0000ff00U) <<  8) | \
+               (((U32)( x )  & 0x00ff0000U) >>  8) | \
+               (((U32)( x )  & 0xff000000U) >> 24)))
+
+/*
+ * Convert U16 value from host byte order to network byte order
+ */
+#define SOCK_HTONS( x )  \
+        ((U16)((((U16)( x )  & 0x00ff) << 8) | \
+               (((U16)( x )  & 0xff00) >> 8)))
+
+/*
+ * Convert U32 value from network byte order to host byte order
+ */
+#define SOCK_NTOHL( x ) \
+        ((U32)((((U32)( x ) & 0x000000ffU) << 24) | \
+               (((U32)( x ) & 0x0000ff00U) <<  8) | \
+               (((U32)( x ) & 0x00ff0000U) >>  8) | \
+               (((U32)( x ) & 0xff000000U) >> 24)))
+
+/*
+ * Convert U16 value from network byte order to host byte order
+ */
+#define SOCK_NTOHS( x ) \
+        ((U16)((((U16)( x ) & 0x00ff) << 8) | \
+               (((U16)( x ) & 0xff00) >> 8)))
+
+/*
+ * Construct IP address in network byte order from single octets.
+ */
+#define SOCK_MK_IPADDR( a, b, c, d ) \
+        ((T_SOCK_IPADDR)((a << 24) | (b << 16) | (c << 8) | d))
+
+/*
+ * Type of a Socket API event
+ */
+typedef enum {
+  SOCK_CREATE_CNF      =  1, /* Result event of sock_create() */
+  SOCK_CLOSE_CNF       =  2, /* Result event of sock_close() */
+  SOCK_BIND_CNF        =  3, /* Result event of sock_bind() */
+  SOCK_LISTEN_CNF      =  4, /* Result event of sock_listen() */
+  SOCK_CONNECT_CNF     =  5, /* Result event of sock_connect() */
+  SOCK_SOCKNAME_CNF    =  6, /* Result event of sock_getsockname() */
+  SOCK_PEERNAME_CNF    =  7, /* Result event of sock_getpeername() */
+  SOCK_HOSTINFO_CNF    =  8, /* Result event of sock_gethostbyname() or sock_gethostbyaddr() */
+  SOCK_MTU_SIZE_CNF    =  9, /* Result event of sock_get_mtu_size() */
+  SOCK_RECV_IND        = 10, /* Network event: data has been received */
+  SOCK_CONNECT_IND     = 11, /* Network event: an incoming connection has been accepted. */
+  SOCK_CONN_CLOSED_IND = 12, /* Network event: connection has been closed by the remote peer */
+  SOCK_ERROR_IND       = 13, /* Network event: an asynchronous error has occurred */
+  SOCK_FLOW_READY_IND  = 14, /* Flow control: the API is ready to send data again */
+
+  SOCK_OPEN_BEARER_CNF,      // Result Event of sock_open_bearer()
+  SOCK_CLOSE_BEARER_CNF,     // Result event of sock_close_bearer()
+  SOCK_BEARER_INFO_CNF,      // Result event of sock_bearer_info()
+  SOCK_BAERER_CLOSED_IND     // The bearer connection has been closed
+} T_SOCK_EVENTTYPE;
+
+/*
+ * Result codes of the API functions to indicate success or an error condition.
+ * This type is used as the result code of the function and as the result value
+ * in the associated event. It is also used for the error codes of a
+ * 'SOCK_ERROR_IND' event
+ */
+typedef enum {
+  SOCK_RESULT_OK                =  0, /* No problem detected. a corresponding primitive has been sent to the TCP/IP entity */
+  SOCK_RESULT_INVALID_PARAMETER =  1, /* A parameter given to the function is invalid */
+  SOCK_RESULT_INTERNAL_ERROR    =  2, /* An internal error has happened */
+  SOCK_RESULT_ADDR_IN_USE       =  3, /* The address or port is already in use */
+  SOCK_RESULT_OUT_OF_MEMORY     =  4, /* There is not enough memory to fulfill the request */
+  SOCK_RESULT_NOT_SUPPORTED     =  5, /* The socket is not of a type that can support this operation */
+  SOCK_RESULT_UNREACHABLE       =  6, /* The specified host cannot be reached */
+  SOCK_RESULT_CONN_REFUSED      =  7, /* The connection to the specified address was refused by the remote host */
+  SOCK_RESULT_TIMEOUT           =  8, /* The connection attempt timed out without establishing a connection */
+  SOCK_RESULT_IS_CONNECTED      =  9, /* The request could not be fulfilled because the socket is already connected */
+  SOCK_RESULT_HOST_NOT_FOUND    = 10, /* The specified host could not be found in the DNS */
+  SOCK_RESULT_DNS_TEMP_ERROR    = 11, /* A temporary DNS error has occurred. Retrying the query may be successful */
+  SOCK_RESULT_DNS_PERM_ERROR    = 12, /* A permanent DNS error has occurred */
+  SOCK_RESULT_NO_IPADDR         = 13, /* The specified name has been found in the DNS, but no IP address is available */
+  SOCK_RESULT_NOT_CONNECTED     = 14, /* The socket has not been connected yet */
+  SOCK_RESULT_MSG_TOO_BIG       = 15, /* The size of the data buffer is too large for a UDP socket */
+  SOCK_RESULT_CONN_RESET        = 16, /* The connection has been reset by the remote peer */
+  SOCK_RESULT_CONN_ABORTED      = 17, /* The connection was aborted due to timeout or some other error condition */
+  SOCK_RESULT_NO_BUFSPACE       = 18, /* Sending failed temporarily because the space to buffer the message was exhausted. */
+  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.
+  SOCK_RESULT_NOT_READY, //	The operation failed because the bearer connection has not been opened.
+  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.
+  SOCK_RESULT_IN_PROGRESS, //	The operation failed because a similar operation is already in progress.
+  SOCK_RESULT_BEARER_ACTIVE//	The operation failed because a bearer connection is already open.
+} T_SOCK_RESULT;
+
+
+/* Type of the bearer_select parameter of sock_open_bearer(), used to select the
+ * type of the bearer connection to be opened by the Data Connection Manager 
+ * (DCM), and of the bearer_type field of the T_SOCK_BEARER_INFO struct.
+ */
+typedef enum {
+  SOCK_BEARER_ANY = DCM_SOCK_BEARER_ANY,
+  SOCK_BEARER_GPRS = DCM_SOCK_BEARER_GPRS,
+  SOCK_BEARER_GSM = DCM_SOCK_BEARER_GSM,
+  SOCK_BEARER_USE_PROFILE = DCM_SOCK_BEARER_USE_PROFILE,
+  SOCK_BEARER_AS_SPECIFIED = DCM_SOCK_BEARER_AS_SPECIFIED
+} T_SOCK_BEARER_TYPE;
+
+// FST: ?????
+typedef enum {
+  SOCK_AUTH_PAP = DCM_SOCK_AUTH_PAP,
+  SOCK_AUTH_CHAP = DCM_SOCK_AUTH_CHAP,
+  SOCK_AUTH_NO= DCM_SOCK_AUTH_NO
+} T_SOCK_AUTHTYPE;
+
+/*
+ * Type of the generic event data structure passed
+ * to the callback function on an event.
+ * The actual event structure may be bigger(depending on its type),
+ * but it will contain these fields at the beginning
+ */
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+} T_SOCK_EVENTSTRUCT;
+
+/*
+ * Pointer to the callback function specified by the application
+ */
+typedef void (*T_SOCK_CALLBACK)(T_SOCK_EVENTSTRUCT* event, void *context);
+
+/* System wide handle of a bearer connection.
+ * Variables of this type are used as handles to identify a bearer connection. 
+ * !! NOT NEEDED FOR CURRENT IMPLEMENTATION ONLY MENTIONED FOR FUTURE SUPPOSE.!!
+ */
+typedef U16 T_SOCK_BEARER_HANDLE;
+
+typedef struct {
+  T_SOCK_BEARER_HANDLE bearer_handle;
+  T_HANDLE             app_handle;
+  T_SOCK_BEARER_TYPE   bearer_type;
+  BOOL                 apn_valid;
+  char                 apn[SOCK_MAX_APN_LEN+1];
+  BOOL                 phone_nr_valid;
+  char                 phone_nr[SOCK_MAX_PHONENUM_LEN+1];
+  BOOL                 user_id_valid;
+  char                 user_id[SOCK_MAX_USERID_LEN+1];
+  BOOL                 password_valid;
+  char                 password[SOCK_MAX_PASSWORD_LEN+1];
+  int                  cid;
+  T_SOCK_IPADDR        ip_address;
+  T_SOCK_IPADDR        dns1;
+  T_SOCK_IPADDR        dns2;
+  T_SOCK_IPADDR        gateway;
+  T_SOCK_AUTHTYPE      authtype;
+  BOOL                 data_compr;
+  BOOL                 header_comp;
+  int                  precedence;
+  int                  delay;
+  int                  reliability;
+  int                  peak_throughput;
+  int                  mean_througput;
+  BOOL                 shareable;
+} T_SOCK_BEARER_INFO;
+
+/* ========================================================================== */
+/* ==============================  Result Events from TCPIP ================= */
+
+typedef struct {
+  T_SOCK_EVENTTYPE     event_type;  /* Type of the event. */
+  T_SOCK_RESULT        result;      /* Result code of the operation */
+  T_SOCK_SOCKET        socket;      /* Socket for which the event occurred */
+  T_SOCK_BEARER_HANDLE bearer_handle;
+} T_SOCK_OPEN_BEARER_CNF;
+
+typedef T_SOCK_EVENTSTRUCT T_SOCK_CLOSE_BEARER_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  T_SOCK_BEARER_INFO bearer_params;
+} T_SOCK_BEARER_INFO_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  U32                dcm_error;   /* The parameter contains errors received from
+                                   * PS (ETSI Spec 07.07) */
+} T_SOCK_BAERER_CLOSED_IND;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+} T_SOCK_CREATE_CNF;
+
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_CLOSE_CNF;
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_BIND_CNF;
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_LISTEN_CNF;
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONNECT_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  T_SOCK_IPADDR      ipaddr;      /* The local IP address of the socket */
+  T_SOCK_PORT        port;        /* The local port number of the socket */
+} T_SOCK_SOCKNAME_CNF;
+
+typedef T_SOCK_SOCKNAME_CNF   T_SOCK_PEERNAME_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* unused */
+  char               hostname[SOCK_MAXHOSTNAMELEN+1]; /* The name of the host as 
+                                                      a zero-terminated string */
+  T_SOCK_IPADDR      ipaddr;      /* The local IP address of the socket */
+} T_SOCK_HOSTINFO_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  U16                mtu_size;    /* MTU size */
+} T_SOCK_MTU_SIZE_CNF;
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  U32                data_length; /* Length of the data portion received. */
+  char               *data_buffer; /*  Pointer to the data received. The application
+                                       shall free this data buffer after use. */
+} T_SOCK_RECV_IND;
+
+
+typedef struct {
+  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
+  T_SOCK_RESULT      result;      /* Result code of the operation */
+  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
+  T_SOCK_SOCKET      new_socket;  /* New socket allocated for the connection. */
+  T_SOCK_IPADDR      peer_ipaddr; /* IP address of the remote peer. */
+  T_SOCK_PORT        peer_port;   /* Port number on the remote side. */
+} T_SOCK_CONNECT_IND;
+
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONN_CLOSED_IND;
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_ERROR_IND;
+typedef T_SOCK_EVENTSTRUCT      T_SOCK_FLOW_READY_IND;
+
+
+
+/* ========================================================================== */
+/* ================== Prototypes of socket API ============================== */
+
+
+/* ******************* API administrative functions ************************* */
+
+/*------------------------------------------------------------------------------
+   Function     : sock_api_initialize
+   Parameter    : - T_SOCK_API_INSTANCE * :
+                    'The function returns an API instance value. The value is needed
+                     for several API functions.'
+                  - T_HANDLE :
+                    'Application task handle as passed to pei_init()'
+                  - char* :
+                    'Name of the application entity as used with vsi_c_open().'
+   Return       : The function returns TRUE if the initialization was successful.
+   Description  : Initializes the socket interface API.
+------------------------------------------------------------------------------*/
+BOOL sock_api_initialize(T_SOCK_API_INSTANCE *api_instance, 
+                         T_HANDLE app_handle,
+                         char* app_name);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_api_deinitialize
+   Parameter    : - T_SOCK_API_INSTANCE :
+                    'API instance value.'
+   Return       : None
+   Description  : Deinitializes the socket interface API. The function releases 
+                  all associated memory.
+------------------------------------------------------------------------------*/
+void sock_api_deinitialize(T_SOCK_API_INSTANCE api_instance);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_api_handles_primitive
+   Parameter    : - T_SOCK_API_INSTANCE: API instance value
+                  - T_PRIM:              Pointer to primitive received from 
+                                         the primitive queue'
+   Return       : The function returns TRUE if the primitive has been handled by 
+                  this function.In this case the application should not do 
+                  anything else with the primitive and should not call PFREE()
+                  to free the memory block used for the primitive.
+                  The function returns FALSE if the primitive has not been 
+                  handled by this function. In this case the application should 
+                  process the primitive as usual. 
+   Description  : Handles primitives for the socket API.
+                  To free the application from the handling of the event 
+                  primitives sent by the TCP/IP entity, the Socket API provides
+                  this function that checks if a primitive is to be handled by 
+                  the Socket API and if it is, handles it. The application is 
+                  supposed to call it immediately after receiving a primitive.
+                  If the primitive is meant for the Socket API, it is handled by
+                  this function. This will in most cases include calling the 
+                  callback function supplied by the application to deliver an 
+                  event. If the primitive is not meant for the Socket API,
+                  no action is taken.
+                  It is recommended to call this function early in the 
+                  application entity's pei_primitive() function.
+------------------------------------------------------------------------------*/
+BOOL sock_api_handles_primitive(T_SOCK_API_INSTANCE api_instance, 
+                                T_PRIM *prim);
+
+
+/* ******************* Bearer related functions ***************************** */
+
+/*------------------------------------------------------------------------------
+   Function     : sock_open_bearer()
+   Parameter    : - T_SOCK_API_INSTANCE: API instance value
+                  - T_SOCK_BEARER_TYPE :  CSD or GPRS
+                  - int:                  Number of the selected profile with a bearer 
+                                          selection of SOCK_BEARER_USE_PROFILE.
+                                          Unused in other cases.
+                  - T_SOCK_BEARER_INFO:   requested parameters of the bearer connection
+                  - T_SOCK_CALLBACK:      callback function to be called for return events.
+                  - void*:                An arbitrary pointer to be passed to the 
+                                          callback function when it is called
+   Return       : T_SOCK_RESULT indicates successor a problem that happend
+   Return Event : T_SOCK_OPEN_BEARER_CNF
+   Description  : Opens a CSD or GPRS connection for use with TCP/IP.
+                  This function a bearer connection for use with TCP/IP. It must be 
+                  called after sock_api_initialize() and before any other 
+                  TCP/IP-related functions.
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_open_bearer(T_SOCK_API_INSTANCE api_instance,
+                               T_SOCK_BEARER_TYPE bearer_select,
+                               int profile_number,
+                               T_SOCK_BEARER_INFO *params,
+                               T_SOCK_CALLBACK sock_cb,
+                               void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_close_bearer()
+   Parameter    : - T_SOCK_API_INSTANCE : API instance value
+                  - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
+                  - T_SOCK_CALLBACK:      Callback function to be called for return events.
+                  - void*:                An arbitrary pointer to be passed to the 
+                                          callback function when it is called
+   Return       : T_SOCK_RESULT indicates successor a problem that happend
+   Return Event : T_SOCK_CLOSE_BEARER_CNF
+   Description  : Close a bearer connection that has been opened with sock_open_bearer().
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_close_bearer(T_SOCK_API_INSTANCE api_instance,
+                                T_SOCK_BEARER_HANDLE bearer_handle,
+                                T_SOCK_CALLBACK sock_cb,
+                                void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_bearer_info()
+   Parameter    : - T_SOCK_API_INSTANCE:  API instance value
+                  - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
+                  - T_SOCK_CALLBACK:      Callback function to be called for 
+                                          return events.
+                  - void*:                An arbitrary pointer to be passed to the 
+                                          callback function when it is called
+   Return       : T_SOCK_RESULT
+   Return Event : T_SOCK_BEARER_INFO_CNF
+   Description  : Get information about a bearer connection that has been opened 
+                  with sock_open_bearer().
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_bearer_info(T_SOCK_API_INSTANCE api_instance,
+                               T_SOCK_BEARER_HANDLE bearer_handle,
+                               T_SOCK_CALLBACK sock_cb,
+                               void *context);
+
+
+/* ******************* Socket related functions ***************************** */
+
+/*------------------------------------------------------------------------------
+   Function     : sock_create
+   Parameter    : - T_SOCK_API_INSTANCE :
+                    'API instance value.'
+                  - T_SOCK_IPPROTO :
+                      'The protocol (UDP or TCP) to be used with this socket'
+                  - T_SOCK_CALLBACK :
+                      'The callback function to be called for events on this socket'
+                  - void * :
+                      'An arbitrary pointer to be passed to 
+                       the callback function when it is called'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_CREATE_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor returned by the TCP/IP entity
+   Description  : - Create a new UDP or TCP socket
+                  - This function creates a socket that can subsequently be used with 
+                    the other Socket API functions
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_create(T_SOCK_API_INSTANCE api_instance,
+                          T_SOCK_IPPROTO ipproto, 
+                          T_SOCK_CALLBACK callback,
+                          void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_close
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to be closed'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_CLOSE_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to be  closed
+   Description  : - Close socket, shutdown connection if present
+                  - This function closes a socket that has previously 
+                    been created with sock_create(). 
+                    If a connection is open for this socket, it will be closed. 
+                    If this socket has listened for connections, 
+                    no further connections will be accepted
+   History      : 0001    03.08.11    shkim    Created
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_close(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_bind
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to be closed'
+                   - T_SOCK_PORT   :
+                      'The port number to bind the socket to'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_BIND_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to be bound
+   Description  : - Bind socket to a specific local port number
+                  - This function binds a socket to the specified local port
+   History      : 0001    03.08.11    shkim    Created
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_bind(T_SOCK_SOCKET socket,
+                        T_SOCK_PORT port);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_listen
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to listen on'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_LISTEN_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to listen on
+   Description  : - Accept TCP connections on this socket
+                  - This function makes TCP/IP listen for 
+                    TCP connections on this socket. 
+                    The socket should have been bound to a specific port 
+                    using sock_bind() before.
+   History      : 0001    03.08.11    shkim    Created
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_listen(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_connect
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to connect'
+                   - T_SOCK_IPADDR :
+                      'The IP address to connect to'
+                   - T_SOCK_PORT   :
+                      'The port number to connect to'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_CONNECT_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to connect
+   Description  : - Connect the socket to a remote endpoint
+                  - With TCP sockets, a TCP connection is established to 
+                      the specified IP address and the specified port. 
+                      The connection can then be used to send data using sock_send(); 
+                      received data is indicated by a SOCK_RECV_IND event.
+                    With UDP sockets, the specified IP address and port number 
+                      are stored with the socket; 
+                      subsequent UDP messages can be sent to this address 
+                      using sock_send(); 
+                      only messages from this address will be received.
+   History      : 0001    03.08.11    shkim    Created
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_connect(T_SOCK_SOCKET socket, 
+                           T_SOCK_IPADDR ipaddr,
+                           T_SOCK_PORT port);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_getsockname
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to retrieve information about'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_SOCKNAME_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to connect
+                    - T_SOCK_IPADDR : The local IP address of the socket
+                    - T_SOCK_PORT   : The local port number of the socket
+   Description  : - Retrieve local address information
+                  - The function retrieves local address information of the socket. 
+                    If the socket has not yet been bound to an address using sock_bind(), 
+                    the port number is unspecified (SOCK_PORT_ANY)
+   History      : 0001    03.08.11    shkim    Created
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_getsockname(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_getpeername
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket descriptor to retrieve information about'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_PEERNAME_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor to connect
+                    - T_SOCK_IPADDR : The IP address of the remote peer
+                    - T_SOCK_PORT   : The port number at the remote peer
+   Description  : - Retrieve remote address information
+                  - The function retrieves address information of 
+                    the connection at the remote peer.
+                    If the socket is not connected, 
+                    the IP address and port number are unspecified
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_getpeername(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_gethostbyname
+   Parameter    : - T_SOCK_API_INSTANCE :
+                      'API instance value.'
+                  - char * :
+                      'The name of the referenced host'
+                   - T_SOCK_CALLBACK :
+                      'The callback function to be called for the result event'
+                   - void * :
+                      'An arbitrary pointer to be passed to the callback
+                       function when it is called'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_HOSTINFO_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the 
+                      host as a zero-terminated string
+                    - T_SOCK_IPADDR : The IP address of the host
+   Description  : - Get the IP address of a host
+                  - The function queries the IP address information of 
+                    the specified host from the DNS.
+                    Because the function is not associated to any socket, 
+                    a callback function and a context 
+                    pointer must be specified separately
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_gethostbyname(T_SOCK_API_INSTANCE api_instance, 
+                                 char *hostname,
+                                 T_SOCK_CALLBACK callback, 
+                                 void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_gethostbyaddr
+   Parameter    : - T_SOCK_API_INSTANCE :
+                      'API instance value.'
+                  - T_SOCK_IPADDR  :
+                      'The IP address of the referenced host'
+                   - T_SOCK_CALLBACK  :
+                      'The callback function to be called for the result event'
+                   - void * :
+                      'An arbitrary pointer to be passed to the callback function 
+                      when it is called'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_HOSTINFO_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the 
+                      host as a zero-terminated string
+                    - T_SOCK_IPADDR : The IP address of the host
+   Description  : - Get the name of a host
+                  - The function queries the hostname for the specified 
+                    IP address from the DNS.
+                    Because the function is not associated to any socket, 
+                    a callback function and a context pointer must be specified separately
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_gethostbyaddr(T_SOCK_API_INSTANCE api_instance,
+                                 T_SOCK_IPADDR ipaddr,
+                                 T_SOCK_CALLBACK callback,
+                                 void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_send
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket to send the data on'
+                   - char * :
+                      'The data buffer to be sent'
+                   - U16 :
+                      'The length of the data buffer in bytes'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Send data on a socket ( TCP only )
+                  - The function sends the specified data buffer over the socket. 
+                    The socket must be connected, 
+                    i. e. it must have been connected to a remote peer 
+                    using sock_connect() or been created when accepting 
+                    a connection as indicated by SOCK_SONNECT_IND.
+                    Implementation note: In order to send the payload data via DTI, 
+                        the data must be copied into a DTI descriptor by the Socket API; 
+                        there is no way to avoid the copy operation without 
+                        putting the burden of knowing DTI-internal data 
+                        structures on the application. 
+                        It has been decided to pay the cost of the copy operation 
+                        in order to free the application from this responsibility
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_send(T_SOCK_SOCKET socket, 
+                        char *buffer, 
+                        U16 buffer_length);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_sendto
+   Parameter    :  - T_SOCK_SOCKET :
+                      'The socket to send the data on'
+                   - char * :
+                      'The data buffer to be sent'
+                   - U16 :
+                      'The length of the data buffer'
+                   - T_SOCK_IPADDR :
+                      'IP address of the host to send data to'
+                   - T_SOCK_PORT :
+                      'Remote port to send data to'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Send data on a socket( UDP only )
+                  - The function sends the specified data buffer 
+                    over the socket to the specified address. The socket must be
+                    a UDP socket.
+                    Implementation note: In order to send the payload data via DTI, 
+                        the data must be copied into a DTI descriptor by the Socket API; 
+                        there is no way to avoid the copy operation without putting 
+                        the burden of knowing DTI-internal data structures on 
+                        the application. It has been decided to pay the cost of 
+                        the copy operation in order to free the application from 
+                        this responsibility
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_sendto(T_SOCK_SOCKET socket, 
+                          char *buffer, 
+                          U16 buffer_length, 
+                          T_SOCK_IPADDR ipaddr, 
+                          T_SOCK_PORT port);
+
+
+/*------------------------------------------------------------------------------------
+   Function     : sock_set_callback
+   Parameter    : - T_SOCK_SOCKET :
+                      'Socket to set callback and context for'
+                  - T_SOCK_CALLBACK :
+                      'New callback function for the socket'
+                  - void * :
+                      'New context pointer for the socket'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Set a new callback function and context pointer for the socket
+                  - The function defines a new callback function and a new context
+                    pointer for the socket. All socket events after this call will be
+                    delivered using the new callback function and the new context
+                    pointer
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_set_callback(T_SOCK_SOCKET socket,
+                                T_SOCK_CALLBACK callback, 
+                                void *context);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_get_callback
+   Parameter    : - T_SOCK_SOCKET :
+                      'Socket to get callback and context from'
+                  - T_SOCK_CALLBACK * :
+                      'Return callback function pointer for the socket'
+                  - void ** :
+                      'Return context pointer for the socket'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Get callback function pointer and context pointer for the socket
+                  - The function returns callback function pointer and context pointer
+                    for the socket.
+                    pointer
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_get_callback(T_SOCK_SOCKET socket,
+                                T_SOCK_CALLBACK *callback_p, 
+                                void **context_p);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_flow_xoff
+   Parameter    :  - T_SOCK_SOCKET :
+                      'Socket to switch to "xoff" status'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Flow control: make TCP/IP stop sending data
+                  - This function makes the Socket API stop TCP/IP sending data.
+                    If TCP/IP has already been stopped, the function has no effect.
+   History      : 0001    03.08.11    shkim    Created
+                  0002    03.09.12    STW      T_SOCK_RESULT added
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_flow_xoff(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_flow_xon
+   Parameter    :  - T_SOCK_SOCKET :
+                      'Socket to switch to "xon" status'
+   Return       : (T_SOCK_RESULT)
+   Return Event : None
+   Description  : - Flow control: make TCP/IP resume sending data
+                  - This function makes TCP/IP resume sending data.
+                    If TCP/IP has not been stopped, the function has no effect
+   History      : 0001    03.08.11    shkim    Created
+                  0002    03.09.12    STW      T_SOCK_RESULT added
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_flow_xon(T_SOCK_SOCKET socket);
+
+
+/*------------------------------------------------------------------------------
+   Function     : sock_get_mtu_size
+   Parameter    :  - T_SOCK_SOCKET :
+                      'Socket to get MTU size from'
+   Return       : (T_SOCK_RESULT)
+   Return Event : 'SOCK_MTU_SIZE_CNF'
+                    - T_SOCK_RESULT : Result code
+                    - T_SOCK_SOCKET : The socket descriptor (unused).
+                    - U16           : MTU size
+   Description  : - Get MTU size of network connection
+                  - The function retrieves the size of 
+                    the Maximum Transfer Unit(MTU) of the network connection.
+   History      : 0001    03.08.11    shkim    Created
+                  0002    03.09.12    STW      T_SOCK_SOCKET added
+------------------------------------------------------------------------------*/
+T_SOCK_RESULT sock_get_mtu_size(T_SOCK_SOCKET socket);
+
+
+#endif  /* __SOCKET_H__ */