Logicrom Socket API¶

Application Example¶

Header File¶

#include <net/sockets.h>

Functions¶

int socket_request(int type)¶

Request a socket

Parameters: type – [in] Socket type see sock_type_e
Returns: Socket ID on success, negative value on error

int socket_setopt(int id, struct sockopt_t *opts)¶

Set socket options

Parameters

id – [in] Socket ID
opts – [in] socket option structure see sockopt_t

Returns

0 on success, negative value on error

int socket_clearopt(int id)¶

Clear socket options/configuration

Note

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

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

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

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

int socket_close(int id)¶

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

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

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

Send data

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

Returns

0 on success, negative value on error

int socket_getstatus(int id)¶

Get socket status

Parameters: id – [in] Socket ID
Returns: returns sock_status_e, on error negative value is returned

int socket_setuserdata(int id, void *arg)¶

Set user data associated with socket sockopt_t::arg

Parameters

id – [in] Socket ID
arg – [in] User data pointer

Returns

0 on success, negative value on error

void *socket_getuserdata(int id)¶

Get user data associated with socket

Parameters: id – [in] Socket ID
Returns: On success returns user data associated

int socket_setserverip(int id, const char *ip)¶

Set server IP

Parameters

id – [in] Socket ID
ip – [in] Server IP or domain name

Returns

0 on success, negative value on error

int socket_setserverport(int id, uint16_t port)¶

Set server port

Parameters

id – [in] Socket ID
port – [in] server port

Returns

0 on success, negative value on error

int socket_setautoconnect(int id, int enable)¶

Enable or disable auto connect

Parameters

id – [in] Socket ID
enable – [in] 1 - Enable, 0 - Disable

Returns

0 on success, negative value on error

int socket_setcallback(int id, struct socket_callback_t *cb)¶

Set socket callbacks

Parameters

id – [in] Socket ID
cb – [in] Callbacks, Can be null to disable callbacks

Returns

0 on success, negative value on error

int socket_free(int id)¶

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

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

int ssl_socket_request(int ssl_version, struct ssl_certs_t *certs)¶

Request an SSL socket.

Parameters

ssl_version – [in] SSL version ssl_ver_e
certs – [in] SSL client certificate and private key. NULL if not used

Returns

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

int ssl_socket_setopt(int id, struct ssl_sockopt_t *opts)¶

Configure SSL socket

Parameters

id – [in] Socket ID
opts – [in] socket configuration see ssl_sockopt_t

Returns

0 on success, negative value on error

int ssl_socket_clearopt(int id)¶

Clear SSL socket configuration

Note

socket must be closed before calling this function

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

int ssl_socket_open(int id)¶

Open SSL socket connection

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

int ssl_socket_close(int id)¶

Close SSL socket

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

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

Send data on SSL socket. This is a blocking call

Parameters

id – [in] Socket ID
buf – [in] Data to send
len – [in] Length of data
timeout – [in] Timeout in seconds, 0 for default (45s)

Returns

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

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

Read data from SSL socket. This is a blocking call

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

Returns

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

int ssl_socket_getstatus(int id)¶

Get socket status

Parameters: id – [in] Socket ID
Returns: returns sock_status_e, on error negative value is returned

int ssl_socket_geterror(int id)¶

Get last error code

Parameters: id – [in] Socket iD
Returns: error code

void *ssl_socket_getuserdata(int id)¶

Get user data associated with socket see ssl_sockopt_t

Parameters: id – [in] Socket ID
Returns: user data pointer

int ssl_socket_free(int id)¶

Release SSL socket

Parameters: id – [in] Socket ID
Returns: 0 on success, negative value on error

Structures¶

struct socket_callback_t¶

Socket callback structure

Public Members

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

Socket status callback

Param sockid: Socket ID
Param event: Socket event see sock_events_e
Param error: Error code in case of error events
Return: Always return 0, return value is unused

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

Socket data receive callback

Param sockid: Socket ID
Param buf: buffer containing receive data
Param len: Length of data
Return: Always return 0, return value is unused

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

Socket transmit callback

Param sockid: Socket ID
Param result: 0 if data sent successfully, -1 if failed
Param buf: buffer containing data which was sent
Param len: length of data
Param arg: user argument passed during send
Return: Always return 0, return value is unused

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¶: 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¶: 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