BSD Socket over Quectel CATM1 on-chip stack API

SF_CELLULAR Socket Framework API on Quectel CATM1. More...

Functions
ssp_err_t	SF_CELLULAR_QCTLCATM1_SOCKET_Open (sf_cellular_socket_ctrl_t *p_ctrl, sf_cellular_socket_cfg_t const *const p_cfg)
	Open the Cellular Device driver to use the Socket Layer on Cellular Driver On-Chip stack. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_SOCKET_Close (sf_cellular_socket_ctrl_t *const p_ctrl)
	Close the Cellular Device driver. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_SOCKET_PING (sf_cellular_socket_ctrl_t *const p_ctrl, ULONG *p_ip_address, uint32_t count, uint32_t interval_ms)
int	socket (int domain, int type, int protocol)
	This creates socket for communication. More...
int	close (int sockfd)
	This closes socket. More...
int	bind (int sockfd, const struct sockaddr *p_local_sock_addr, socklen_t addrlen)
	This binds socket to IP address. More...
int	listen (int sockfd, int backlog)
	This listens for connection on socket. More...
int	connect (int sockfd, const struct sockaddr *p_serv_addr, socklen_t addrlen)
	This connects with remote socket(stream socket). More...
int	accept (int sockfd, struct sockaddr *p_cliaddr, socklen_t *p_addrlen)
	This accepts connection from remote socket. More...
ssize_t	send (int sockfd, const void *p_buf, size_t length, int flags)
	This sends data over STREAM socket. More...
ssize_t	recv (int sockfd, void *p_buf, size_t length, int flags)
	This receives data over STREAM socket. More...
ssize_t	sendto (int sockfd, const void *p_buf, size_t length, int flags, const struct sockaddr *p_dest_addr, socklen_t addrlen)
	This sends data over DGRAM socket. More...
ssize_t	recvfrom (int sockfd, void *p_buf, size_t length, int flags, struct sockaddr *p_src_addr, socklen_t *p_addrlen)
	This receives data over DGRAM socket. More...
int	setsockopt (int sockfd, int level, int optname, const void *p_optval, socklen_t optlen)
	This updates socket specific options. Quectel CATM1 supports following socket options SO_SNDBUF: Transmission packet size TCP_MAX_RETRIES: Maximum Number of retransmission TCP_MAX_RTO: Maximum interval time of TCP retransmission. More...
int	getsockopt (int sockfd, int level, int optname, void *p_optval, socklen_t *p_optlen)
	This reads socket specific options. Quectel CATM1 supports following socket options SO_SNDBUF: Transmission packet size TCP_MAX_RETRIES: Maximum Number of retransmission TCP_MAX_RTO: Maximum interval time of TCP retransmission. More...
int	select (int nfds, fd_set *p_readfds, fd_set *p_writefds, fd_set *p_exceptfds, struct timeval *p_timeout)
	This waits for any activity on socket. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_SOCKET_VersionGet (ssp_version_t *const p_version)
	This function gets the version information of the underlying driver. More...

Detailed Description

SF_CELLULAR Socket Framework API on Quectel CATM1.

Function Documentation

accept()

int accept	(	int	sockfd,
		struct sockaddr *	p_cliaddr,
		socklen_t *	p_addrlen
	)

This accepts connection from remote socket.

Implements accept This function accepts connection from remote socket. This API is used only with socket type STREAM. The call is blocked if no connection is present or the socket is blocking.

Parameters

[in]	sockfd	Socket File Descriptor
[out]	p_cliaddr	Remote machine Network address
[out]	p_addrlen	Size of Socket address structure

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Invalid input arguments OR Error accepting the connection
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Connection is received successfully.

bind()

int bind	(	int	sockfd,
		const struct sockaddr *	p_local_sock_addr,
		socklen_t	addrlen
	)

This binds socket to IP address.

Implements bind This function binds socket to given IP address and port.

Parameters

sockfd	Socket file descriptor
p_local_sock_addr	Socket address structure
addrlen	Size of Socket address structure

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Binding socket failed
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Socket is bound successfully.

close()

int close

(

int

sockfd

)

This closes socket.

Implements close Close opened socket

Parameters

[in]

sockfd

Socket file descriptor

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Invalid input arguments OR Closing socket failed
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Socket is closed successfully.

connect()

int connect	(	int	sockfd,
		const struct sockaddr *	p_serv_addr,
		socklen_t	addrlen
	)

This connects with remote socket(stream socket).

Implements connect This function connects local socket with remote socket. The call is blocked until a connection is established or error is returned.

Parameters

[in]	sockfd	Socket File Descriptor
[in]	p_serv_addr	Remote machine Network address
[in]	addrlen	Size of Socket address structure

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Invalid input arguments OR Error occurred.
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Socket is connected successfully.

getsockopt()

int getsockopt	(	int	sockfd,
		int	level,
		int	optname,
		void *	p_optval,
		socklen_t *	p_optlen
	)

This reads socket specific options. Quectel CATM1 supports following socket options SO_SNDBUF: Transmission packet size TCP_MAX_RETRIES: Maximum Number of retransmission TCP_MAX_RTO: Maximum interval time of TCP retransmission.

Implements getsockopt This gets options for an existing socket.

Parameters

[in]	sockfd	Socket file descriptor
[in]	level	Level
[in]	optname	Socket option name
[out]	p_optval	Socket option value
[out]	p_optlen	Size of Socket option

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Invalid input arguments OR Error reading socket option
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Socket option read successfully.

listen()

int listen	(	int	sockfd,
		int	backlog
	)

This listens for connection on socket.

Implements listen This function listen for connection on socket.

Parameters

[in]	sockfd	Socket File Descriptor
[in]	backlog	number of maximum connection can be accepted

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Failed to set socket in Listen mode
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Set socket in Listen mode successfully.

recv()

ssize_t recv	(	int	sockfd,
		void *	p_buf,
		size_t	length,
		int	flags
	)

This receives data over STREAM socket.

Implements receive This function receives data on a stream socket in connected state. If no packet is available, the socket is blocked until it is set to non-blocking. The application must provide a valid buffer to receive the payload. If the buffer length is smaller than the available payload, the API will do a partial copy, and hold on the rest of the payload for a subsequent call to the API.

Parameters

[in]	sockfd	Socket File Descriptor
[out]	p_buf	Buffer to read data
[in]	length	Data length
[in]	flags	Socket flag

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Invalid input arguments OR Failed to receive data.

Returns

Otherwise Number of Data bytes received successfully.

recvfrom()

ssize_t recvfrom	(	int	sockfd,
		void *	p_buf,
		size_t	length,
		int	flags,
		struct sockaddr *	p_src_addr,
		socklen_t *	p_addrlen
	)

This receives data over DGRAM socket.

Implements recvfrom This function receives data on a dgram socket. If no packet is available, the socket is blocked until it is set to non-blocking. The application must provide a valid buffer to receive the payload. If the buffer length is smaller than the available payload, the API will do a partial copy, and hold on the rest of the payload for a subsequent call to the API.

Parameters

[in]	sockfd	Socket file descriptor
[out]	p_buf	Data buffer pointer to read data
[in]	length	Length of data to read
[in]	flags	Flags
[in]	p_src_addr	Remote machine network address
[in]	p_addrlen	Size of Remote machine network

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Invalid input arguments OR Error receiving data

Returns

Otherwise Numbers of data bytes received successfully.

select()

int select	(	int	nfds,
		fd_set *	p_readfds,
		fd_set *	p_writefds,
		fd_set *	p_exceptfds,
		struct timeval *	p_timeout
	)

This waits for any activity on socket.

Implements select Allow an application thread to block on a given socket handle for a specified time period. This API checks for any activity on specified socket, for example arrival of a packet at the receive queue.

Parameters

[in]	nfds	Number of socket fds in to check
[in]	p_readfds	Read socket fd set
[in]	p_writefds	Write socket fd set. If no descriptor is to be tested for writing, p_writefds should be NULL
[in]	p_exceptfds	Exceptional socket fd set. If no descriptor is to be tested for exceptions, p_exceptfds should be NULL
[in]	p_timeout	Timeout

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Timeout occurred, no activity.

Returns

Otherwise Activity detected(Packet available).

send()

ssize_t send	(	int	sockfd,
		const void *	p_buf,
		size_t	length,
		int	flags
	)

This sends data over STREAM socket.

Implements send This function sends data on a stream socket in connected state.

Parameters

[in]	sockfd	Socket File Descriptor
[in]	p_buf	Buffer data to send
[in]	length	Data length
[in]	flags	Socket flag

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Invalid input arguments OR Failed to send data.

Returns

Otherwise Number of Data bytes sent successfully.

sendto()

ssize_t sendto	(	int	sockfd,
		const void *	p_buf,
		size_t	length,
		int	flags,
		const struct sockaddr *	p_dest_addr,
		socklen_t	addrlen
	)

This sends data over DGRAM socket.

Implements sendto This function sends data to remote.

Parameters

[in]	sockfd	Socket File Descriptor
[in]	p_buf	Buffer data pointer
[in]	length	Length of data
[in]	flags	Flag
[in]	p_dest_addr	Address of remote UDP server
[in]	addrlen	Size of Network address structure

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Invalid input arguments OR Error Sending data.

Returns

Otherwise Numbers of bytes sent successfully.

setsockopt()

int setsockopt	(	int	sockfd,
		int	level,
		int	optname,
		const void *	p_optval,
		socklen_t	optlen
	)

This updates socket specific options. Quectel CATM1 supports following socket options SO_SNDBUF: Transmission packet size TCP_MAX_RETRIES: Maximum Number of retransmission TCP_MAX_RTO: Maximum interval time of TCP retransmission.

Implements setsockopt This sets options for an existing socket.

Parameters

[in]	sockfd	Socket file descriptor
[in]	level	Level
[in]	optname	Socket option name
[in]	p_optval	Socket option value
[in]	optlen	Size of Socket option

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD	Invalid input arguments OR Error setting socket option
SF_CELLULAR_QCTLCATM1_SOCKET_SUCCESS	Socket option set successfully.

SF_CELLULAR_QCTLCATM1_SOCKET_Close()

ssp_err_t SF_CELLULAR_QCTLCATM1_SOCKET_Close

(

sf_cellular_socket_ctrl_t *const

p_ctrl

)

Close the Cellular Device driver.

Implements sf_cellular_socket_api_t::close Calls the low level Cellular device driver's Close API to close the cellular Driver.

Return values

SSP_SUCCESS	Cellular Driver stop successfully.
SSP_ERR_NOT_OPEN	Device is not opened.
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver un-initialization failed
SSP_ERR_IN_USE	Device already in use

SF Cellular instance variable

SF Cellular API structure variable

SF Cellular Stack control block structure

SF_CELLULAR_QCTLCATM1_SOCKET_Open()

ssp_err_t SF_CELLULAR_QCTLCATM1_SOCKET_Open	(	sf_cellular_socket_ctrl_t *	p_ctrl,
		sf_cellular_socket_cfg_t const *const	p_cfg
	)

Open the Cellular Device driver to use the Socket Layer on Cellular Driver On-Chip stack.

Implements sf_cellular_socket_api_t::open Calls the low level Cellular device driver's Open API to Initialize the Cellular Device Driver, for using Socket Layer on On-Chip stack.

Return values

SSP_SUCCESS	Driver initialization successfully.
SSP_ERR_ALREADY_OPEN	Cellular Quectel CATM1 Driver is already opened.
SSP_ERR_CELLULAR_CONFIG_FAILED	Cellular Quectel CATM1 module Configuration failed
SSP_ERR_CELLULAR_INIT_FAILED	Cellular Quectel CATM1 module initialization failed
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver initialization failed
SSP_ERR_IN_USE	Device already in use

SF Cellular instance variable

SF Cellular API structure variable

SF Cellular configuration structure variable

SF Cellular Stack control block structure

Initialize Cellular Modem

Initialize Socket Interface global variable , if module open successfully or already open

SF_CELLULAR_QCTLCATM1_SOCKET_PING()

ssp_err_t SF_CELLULAR_QCTLCATM1_SOCKET_PING	(	sf_cellular_socket_ctrl_t *const	p_ctrl,
		ULONG *	p_ip_address,
		uint32_t	count,
		uint32_t	interval_ms
	)

Ping an IP address on the network.

Parameters

[in]	p_ctrl	Pointer to control structure.
[in]	p_ip_address	Pointer to IP address.
[in]	count	Number of ping attempts.
[in]	interval_ms	Interval between ping attempts.

Return values

SSP_ERR_UNSUPPORTED

Functionality not supported

SF_CELLULAR_QCTLCATM1_SOCKET_VersionGet()

ssp_err_t SF_CELLULAR_QCTLCATM1_SOCKET_VersionGet

(

ssp_version_t *const

p_version

)

This function gets the version information of the underlying driver.

Implements sf_cellular_socket_api_t::versionGet

Parameters

[out]

p_version

Driver version information

Return values

SSP_ERR_ASSERTION	Argument NULL is passed
SSP_SUCCESS	Successfully read version information

socket()

int socket	(	int	domain,
		int	type,
		int	protocol
	)

This creates socket for communication.

Implements socket Creates socket with given parameters.

Parameters

[in]	domain	Network Domain
[in]	type	Socket type
[in]	protocol	Protocol type

Return values

SF_CELLULAR_QCTLCATM1_SOCKET_INVALID_FD

Socket creation failed

Returns

Otherwise Socket descriptor of newly created socket