RAW Socket API

Header File

Functions

int socket_request(int type)

Request a socket

Return

Socket ID on success, negative value on error

Parameters

int socket_setopt(int id, struct sockopt_t *opts)

Set socket options

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • opts: [in] socket option sturcture see sockopt_t

int socket_clearopt(int id)

Clear socket options/configuration

Note

socket must be closed before clearing else -EINVAL will be returned

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int socket_open(int id)

Open a socket. socket options must be configured before calling this function. This is a non blocking function, connection status will be returned via status callback

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int socket_close(int id)

Close a socket. This is a non-blocking function, status will be returned via status callback

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int socket_send(int id, const void *buf, int len, int timeout, void *arg)

Send data

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • buf: [in] Data to send

  • len: [in] Length of data

  • timeout: [in] Timeout in seconds, 0 for default timeout (45s)

  • arg: [in] User data argument, This argument will be passed to transmit callback function

int socket_getstatus(int id)

Get socket status

Return

returns sock_status_e, on error negative value is returned

Parameters

  • id: [in] Socket ID

int socket_setuserdata(int id, void *arg)

Set user data associated with socket sockopt_t::arg

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • arg: [in] User data pointer

void *socket_getuserdata(int id)

Get user data associated with socket

Return

On success returns user data associated

Parameters

  • id: [in] Socket ID

int socket_setserverip(int id, const char *ip)

Set server IP

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • ip: [in] Server IP or domain name

int socket_setserverport(int id, uint16_t port)

Set server port

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • port: [in] server port

int socket_setautoconnect(int id, int enable)

Enable or disable auto connect

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • enable: [in] 1 - Enable, 0 - Disable

int socket_setcallback(int id, struct socket_callback_t *cb)

Set socket callbacks

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • cb: [in] Callbacks, Can be null to disable callbacks

int socket_free(int id)

Release socket. If socket is not closed it will be closed first.

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int ssl_socket_request(int ssl_version, struct ssl_certs_t *certs)

Request an SSL socket.

Return

On success SSL socket ID is returned, On error negative value is returned

Parameters

  • ssl_version: [in] SSL version ssl_ver_e

  • certs: [in] SSL client certificate and private key. NULL if not used

int ssl_socket_setopt(int id, struct ssl_sockopt_t *opts)

Configure SSL socket

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

  • opts: [in] socket configuration see ssl_sockopt_t

int ssl_socket_clearopt(int id)

Clear SSL socket configuration

Note

socket must be closed before calling this function

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int ssl_socket_open(int id)

Open SSL socket connection

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int ssl_socket_close(int id)

Close SSL socket

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

int ssl_socket_send(int id, const void *buf, int len, int timeout)

Send data on SSL socket. This is a blocking call

Return

returns number of bytes sent successfully, on error negative value is returned

Parameters

  • id: [in] Socket ID

  • buf: [in] Data to send

  • len: [in] Length of data

  • timeout: [in] Timeout in seconds, 0 for default (45s)

int ssl_socket_read(int id, void *buf, int len, int timeout)

Read data from SSL socket. This is a blocking call

Return

returns number of bytes read, on error negative value is returned

Parameters

  • id: [in] Socket ID

  • buf: [out] Buffer pointer to store data

  • len: [in] Length data to read

  • timeout: [in] Timeout in seconds, If 0 function will block until data is received or interrupted by error

int ssl_socket_getstatus(int id)

Get socket status

Return

returns sock_status_e, on error negative value is returned

Parameters

  • id: [in] Socket ID

int ssl_socket_geterror(int id)

Get last error code

Return

error code

Parameters

  • id: [in] Socket iD

void *ssl_socket_getuserdata(int id)

Get user data associated with socket see ssl_sockopt_t

Return

user data pointer

Parameters

  • id: [in] Socket ID

int ssl_socket_free(int id)

Release SSL socket

Return

0 on success, negative value on error

Parameters

  • id: [in] Socket ID

Structures

struct socket_callback_t

Socket callback structure

Public Members

int (*status_callback)(int sockid, int event, int error)

Socket status callback

Return

Always return 0, return value is unused

Parameters

  • sockid: Socket ID

  • event: Socket event see sock_events_e

  • error: Error code in case of error events

int (*recv_callback)(int sockid, const void *buf, int len)

Socket data receive callback

Return

Always return 0, return value is unused

Parameters

  • sockid: Socket ID

  • buf: buffer containing receive data

  • len: Length of data

int (*xmit_callback)(int sockid, int result, const void *buf, int len, void *arg)

Socket transmit callback

Return

Always return 0, return value is unused

Parameters

  • sockid: Socket ID

  • result: 0 if data sent successfully, -1 if failed

  • buf: buffer containing data which was sent

  • len: length of data

  • arg: user argument passed during send

struct sockopt_t

Socket configuration option

Public Members

char server_ip[100]

IP/Domain name of server

int port

Server port to connect

const struct socket_callback_t *handlers

socket callback functions see socket_callback_t

unsigned char autoconnect

Auto-connect server on disconnection. 1 for auto-connect, When 0 socket_open must be called to reconnect to server

void *arg

user data to associate with socket

struct ssl_sockopt_t

SSL Socket configuration

Public Members

char server_ip[100]

IP/Domain name of server

int port

SSL server port

int (*status_callback)(int sockid, int status)

SSL socket status callback

void *arg

user data to associate with socket

struct ssl_certs_t

SSL client certificates

Public Members

int cert_type

Input type see ssl_type_e

const void *cert

filename/buffer containing certificate (Only PEM format supported)

int cert_len

Length of certificate in case buffer is provided

int pkey_type

Input type see ssl_type_e

const void *privatekey

filename/buffer containing private key (Only PEM format supported)

int privatekey_len

Length of private key in case buffer is provided

Macros

SOC_WRITE_TO_DEFAULT

Enumerations

enum sock_type_e

Socket Type

Values:

enumerator SOCK_TYPE_TCP

TCP socket

enumerator SOCK_TYPE_UDP

UDP Datagram socket

enum sock_status_e

Socket status

Values:

enumerator SOCK_STA_NOGPRS

No GPRS available

enumerator SOCK_STA_CONNECTED

Socket is connected

enumerator SOCK_STA_DISCONNECTED

Socket is disconnected

enum sock_events_e

Socket status callback events

Values:

enumerator SOCK_EV_CONNECTED = 1

Socket connect event. This event will also come in case of UDP when socket is ready.

enumerator SOCK_EV_DISCONNECTED

Socket disconnect event. This event will also come in case of UDP when socket is not ready to send or receive after a network failure

enumerator SOCK_EV_RELEASED

Socket is freed.

enumerator SOCK_EV_CONN_FAILED

TCP connection to server failed.

enumerator SOCK_EV_WRITE_FAILED

TCP socket write failed. Either write timeout has occurred or network error.

enumerator SOCK_EV_READ_FAILED

TCP socket read failed.

enumerator SOCK_EV_GPRS_FAILED

GPRS bearer failed.

enum ssl_ver_e

SSL version

Values:

enumerator SSL_VER_DEFAULT

Default SSL version (TLS 1.2)

enumerator TLS_VER_1V2 = SSL_VER_DEFAULT

TLS v1.2

enumerator TLS_VER_1V1

TLS v1.1

enumerator TLS_VER_1V0

TLS v1.0

enumerator SSL_VER_3V0

SSL v3

enum ssl_type_e

SSL certificate input type

Values:

enumerator SSL_TYPE_BUFFER

certificate provided as a buffer

enumerator SSL_TYPE_FILE

certificate provided as a filename