API  2.2
TSmarT Software Library
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions

Functions

int socket (long domain, long type, long protocol)
 create an endpoint for communication The socket function creates a socket that is bound to a specific transport service provider. This function is called by the application layer to obtain a socket handle. More...
 
long closesocket (long sd)
 The socket function closes a created socket. More...
 
long accept (long sd, sockaddr *addr, socklen_t *addrlen)
 accept a connection on a socket: This function is used with connection-based socket types (SOCK_STREAM). It extracts the first connection request on the queue of pending connections, creates a new connected socket, and returns a new file descriptor referring to that socket. The newly created socket is not in the listening state. The original socket sd is unaffected by this call. The argument sd is a socket that has been created with socket(), bound to a local address with bind(), and is listening for connections after a listen(). The argument addr is a pointer to a sockaddr structure. This structure is filled in with the address of the peer socket, as known to the communications layer. The exact format of the address returned addr is determined by the socket's address family. The addrlen argument is a value-result argument: it should initially contain the size of the structure pointed to by addr, on return it will contain the actual length (in bytes) of the address returned. More...
 
long bind (long sd, const sockaddr *addr, long addrlen)
 assign a name to a socket This function gives the socket the local address addr. addr is addrlen bytes long. Traditionally, this is called when a socket is created with socket, it exists in a name space (address family) but has no name assigned. It is necessary to assign a local address before a SOCK_STREAM socket may receive connections. More...
 
long listen (long sd, long backlog)
 listen for connections on a socket The willingness to accept incoming connections and a queue limit for incoming connections are specified with listen(), and then the connections are accepted with accept. The listen() call applies only to sockets of type SOCK_STREAM The backlog parameter defines the maximum length the queue of pending connections may grow to. More...
 
int gethostbyname (char *hostname, unsigned short usNameLen, unsigned long *out_ip_addr)
 Get host IP by name. Obtain the IP Address of machine on network, by its name. More...
 
long connect (long sd, const sockaddr *addr, long addrlen)
 initiate a connection on a socket Function connects the socket referred to by the socket descriptor sd, to the address specified by addr. The addrlen argument specifies the size of addr. The format of the address in addr is determined by the address space of the socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. The other socket is specified by address, which is an address in the communications space of the socket. Note that the function implements only blocking behavior thus the caller will be waiting either for the connection establishment or for the connection establishment failure. More...
 
int select (long nfds, fd_set_wifi *readsds, fd_set_wifi *writesds, fd_set_wifi *exceptsds, struct timeval_t *timeout)
 Monitor socket activity Select allow a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation. More...
 
int setsockopt (long sd, long level, long optname, const void *optval, socklen_t optlen)
 set socket options This function manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; The parameters optval and optlen are used to access optval - use for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by option_value, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, option_value may be NULL. More...
 
int getsockopt (long sd, long level, long optname, void *optval, socklen_t *optlen)
 set socket options This function manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; The parameters optval and optlen are used to access optval - use for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by option_value, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, option_value may be NULL. More...
 
int recv (long sd, void *buf, long len, long flags)
 function receives a message from a connection-mode socket More...
 
int recvfrom (long sd, void *buf, long len, long flags, sockaddr *from, socklen_t *fromlen)
 read data from socket function receives a message from a connection-mode or connectionless-mode socket. Note that raw sockets are not supported. More...
 
int send (long sd, const void *buf, long len, long flags)
 Write data to TCP socket This function is used to transmit a message to another socket. More...
 
int sendto (long sd, const void *buf, long len, long flags, const sockaddr *to, socklen_t tolen)
 Write data to TCP socket This function is used to transmit a message to another socket. More...
 
int mdnsAdvertiser (unsigned short mdnsEnabled, char *deviceServiceName, unsigned short deviceServiceNameLength)
 Set CC3000 in mDNS advertiser mode in order to advertise itself. More...
 

Detailed Description

Function Documentation

long accept ( long  sd,
sockaddr *  addr,
socklen_t *  addrlen 
)

accept a connection on a socket: This function is used with connection-based socket types (SOCK_STREAM). It extracts the first connection request on the queue of pending connections, creates a new connected socket, and returns a new file descriptor referring to that socket. The newly created socket is not in the listening state. The original socket sd is unaffected by this call. The argument sd is a socket that has been created with socket(), bound to a local address with bind(), and is listening for connections after a listen(). The argument addr is a pointer to a sockaddr structure. This structure is filled in with the address of the peer socket, as known to the communications layer. The exact format of the address returned addr is determined by the socket's address family. The addrlen argument is a value-result argument: it should initially contain the size of the structure pointed to by addr, on return it will contain the actual length (in bytes) of the address returned.

accept

Parameters
[in]sdsocket descriptor (handle)
[out]addrthe argument addr is a pointer to a sockaddr structure This structure is filled in with the address of the peer socket, as known to the communications layer. determined. The exact format of the address returned addr is by the socket's address sockaddr. On this version only AF_INET is supported. This argument returns in network order.
[out]addrlenthe addrlen argument is a value-result argument: it should initially contain the size of the structure pointed to by addr.
Returns
For socket in blocking mode: On success, socket handle. on failure negative For socket in non-blocking mode:
  • On connection establishment, socket handle
  • On connection pending, SOC_IN_PROGRESS (-2)
  • On failure, SOC_ERROR (-1)
See Also
socket ; bind ; listen
Examples:
wifi_tcp_client_server.c, and wifi_tcp_server.c.
long bind ( long  sd,
const sockaddr *  addr,
long  addrlen 
)

assign a name to a socket This function gives the socket the local address addr. addr is addrlen bytes long. Traditionally, this is called when a socket is created with socket, it exists in a name space (address family) but has no name assigned. It is necessary to assign a local address before a SOCK_STREAM socket may receive connections.

bind

Parameters
[in]sdsocket descriptor (handle)
[out]addrspecifies the destination address. On this version only AF_INET is supported.
[out]addrlencontains the size of the structure pointed to by addr.
Returns
On success, zero is returned. On error, -1 is returned.
See Also
socket ; accept ; listen
Examples:
wifi_tcp_client_server.c, and wifi_tcp_server.c.
long closesocket ( long  sd)

The socket function closes a created socket.

closesocket

Parameters
sdsocket handle.
Returns
On success, zero is returned. On error, -1 is returned.
Examples:
wifi_tcp_client.c, wifi_tcp_client_server.c, and wifi_tcp_server.c.
long connect ( long  sd,
const sockaddr *  addr,
long  addrlen 
)

initiate a connection on a socket Function connects the socket referred to by the socket descriptor sd, to the address specified by addr. The addrlen argument specifies the size of addr. The format of the address in addr is determined by the address space of the socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. The other socket is specified by address, which is an address in the communications space of the socket. Note that the function implements only blocking behavior thus the caller will be waiting either for the connection establishment or for the connection establishment failure.

connect

Parameters
[in]sdsocket descriptor (handle)
[in]addrspecifies the destination addr. On this version only AF_INET is supported.
[out]addrlencontains the size of the structure pointed to by addr
Returns
On success, zero is returned. On error, -1 is returned
See Also
socket
Examples:
mqtt_wifi_publisher.c, mqtt_wifi_subscriber.c, wifi_tcp_client.c, and wifi_tcp_client_server.c.
int gethostbyname ( char *  hostname,
unsigned short  usNameLen,
unsigned long *  out_ip_addr 
)

Get host IP by name. Obtain the IP Address of machine on network, by its name.

gethostbyname

Parameters
[in]hostnamehost name
[in]usNameLenname length
[out]out_ip_addrThis parameter is filled in with host IP address. In case that host name is not resolved, out_ip_addr is zero.
Returns
On success, positive is returned. On error, negative is returned
Note
On this version, only blocking mode is supported. Also note that the function requires DNS server to be configured prior to its usage.
Examples:
wifi_tcp_client.c, and wifi_tcp_client_server.c.
int getsockopt ( long  sd,
long  level,
long  optname,
void *  optval,
socklen_t *  optlen 
)

set socket options This function manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; The parameters optval and optlen are used to access optval - use for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by option_value, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, option_value may be NULL.

getsockopt

Parameters
[in]sdsocket handle
[in]leveldefines the protocol level for this option
[in]optnamedefines the option name to Interrogate
[out]optvalspecifies a value for the option
[out]optlenspecifies the length of the option value
Returns
On success, zero is returned. On error, -1 is returned
Note
On this version the following two socket options are enabled: The only protocol level supported in this version is SOL_SOCKET (level).
  1. SOCKOPT_RECV_TIMEOUT (optname) SOCKOPT_RECV_TIMEOUT configures recv and recvfrom timeout in milliseconds. In that case optval should be pointer to unsigned long.
  2. SOCKOPT_NONBLOCK (optname). sets the socket non-blocking mode on or off. In that case optval should be SOCK_ON or SOCK_OFF (optval).
See Also
setsockopt
long listen ( long  sd,
long  backlog 
)

listen for connections on a socket The willingness to accept incoming connections and a queue limit for incoming connections are specified with listen(), and then the connections are accepted with accept. The listen() call applies only to sockets of type SOCK_STREAM The backlog parameter defines the maximum length the queue of pending connections may grow to.

listen

Parameters
[in]sdsocket descriptor (handle)
[in]backlogspecifies the listen queue depth. On this version backlog is not supported.
Returns
On success, zero is returned. On error, -1 is returned.
See Also
socket ; accept ; bind
Note
On this version, backlog is not supported
Examples:
wifi_tcp_client_server.c, and wifi_tcp_server.c.
int mdnsAdvertiser ( unsigned short  mdnsEnabled,
char *  deviceServiceName,
unsigned short  deviceServiceNameLength 
)

Set CC3000 in mDNS advertiser mode in order to advertise itself.

mdnsAdvertiser

Parameters
[in]mdnsEnabledflag to enable/disable the mDNS feature
[in]deviceServiceNameService name as part of the published canonical domain name
[in]deviceServiceNameLengthLength of the service name
Returns
On success, zero is returned, return SOC_ERROR if socket was not opened successfully, or if an error occurred.
int recv ( long  sd,
void *  buf,
long  len,
long  flags 
)

function receives a message from a connection-mode socket

recv

Parameters
[in]sdsocket handle
[out]bufPoints to the buffer where the message should be stored
[in]lenSpecifies the length in bytes of the buffer pointed to by the buffer argument.
[in]flagsSpecifies the type of message reception. On this version, this parameter is not supported.
Returns
Return the number of bytes received, or -1 if an error occurred
See Also
recvfrom
Note
On this version, only blocking mode is supported.
Examples:
mqtt_wifi_publisher.c, mqtt_wifi_subscriber.c, wifi_tcp_client.c, wifi_tcp_client_server.c, and wifi_tcp_server.c.
int recvfrom ( long  sd,
void *  buf,
long  len,
long  flags,
sockaddr *  from,
socklen_t *  fromlen 
)

read data from socket function receives a message from a connection-mode or connectionless-mode socket. Note that raw sockets are not supported.

recvfrom

Parameters
[in]sdsocket handle
[out]bufPoints to the buffer where the message should be stored
[in]lenSpecifies the length in bytes of the buffer pointed to by the buffer argument.
[in]flagsSpecifies the type of message reception. On this version, this parameter is not supported.
[in]frompointer to an address structure indicating the source address: sockaddr. On this version only AF_INET is supported.
[in]fromlensource address structure size
Returns
Return the number of bytes received, or -1 if an error occurred
See Also
recv
Note
On this version, only blocking mode is supported.

recvfrom

Parameters
[in]sdsocket handle
[out]bufPoints to the buffer where the message should be stored
[in]lenSpecifies the length in bytes of the buffer pointed to by the buffer argument.
[in]flagsSpecifies the type of message reception. On this version, this parameter is not supported.
[in]frompointer to an address structure indicating the source address: sockaddr. On this version only AF_INET is supported.
[in]fromlensource address tructure size
Returns
Return the number of bytes received, or -1 if an error occurred
See Also
recv
Note
On this version, only blocking mode is supported.
int select ( long  nfds,
fd_set_wifi *  readsds,
fd_set_wifi *  writesds,
fd_set_wifi *  exceptsds,
struct timeval_t *  timeout 
)

Monitor socket activity Select allow a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation.

select

Parameters
[in]nfdsthe highest-numbered file descriptor in any of the three sets, plus 1.
[out]writesdssocket descriptors list for write monitoring
[out]readsdssocket descriptors list for read monitoring
[out]exceptsdssocket descriptors list for exception monitoring
[in]timeoutis an upper bound on the amount of time elapsed before select() returns. Null means infinity timeout. The minimum timeout is 5 milliseconds, less than 5 milliseconds will be set automatically to 5 milliseconds.
Returns
On success, select() returns the number of file descriptors contained in the three returned descriptor sets (that is, the total number of bits that are set in readfds, writefds, exceptfds) which may be zero if the timeout expires before anything interesting happens. On error, -1 is returned. *readsds - return the sockets on which Read request will return without delay with valid data. *writesds - return the sockets on which Write request will return without delay. *exceptsds - return the sockets which closed recently.
Note
If the timeout value set to less than 5ms it will automatically set to 5ms to prevent overload of the system
See Also
socket
int send ( long  sd,
const void *  buf,
long  len,
long  flags 
)

Write data to TCP socket This function is used to transmit a message to another socket.

send

Parameters
sdsocket handle
bufPoints to a buffer containing the message to be sent
lenmessage size in bytes
flagsOn this version, this parameter is not supported
Returns
Return the number of bytes transmitted, or -1 if an error occurred
Note
On this version, only blocking mode is supported.
See Also
sendto
Examples:
mqtt_wifi_publisher.c, mqtt_wifi_subscriber.c, wifi_tcp_client.c, wifi_tcp_client_server.c, and wifi_tcp_server.c.
int sendto ( long  sd,
const void *  buf,
long  len,
long  flags,
const sockaddr *  to,
socklen_t  tolen 
)

Write data to TCP socket This function is used to transmit a message to another socket.

sendto

Parameters
sdsocket handle
bufPoints to a buffer containing the message to be sent
lenmessage size in bytes
flagsOn this version, this parameter is not supported
topointer to an address structure indicating the destination address: sockaddr. On this version only AF_INET is supported.
tolendestination address structure size
Returns
Return the number of bytes transmitted, or -1 if an error occurred
Note
On this version, only blocking mode is supported.
See Also
send
int setsockopt ( long  sd,
long  level,
long  optname,
const void *  optval,
socklen_t  optlen 
)

set socket options This function manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; The parameters optval and optlen are used to access optval - use for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by option_value, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, option_value may be NULL.

setsockopt

Parameters
[in]sdsocket handle
[in]leveldefines the protocol level for this option
[in]optnamedefines the option name to Interrogate
[in]optvalspecifies a value for the option
[in]optlenspecifies the length of the option value
Returns
On success, zero is returned. On error, -1 is returned
Note
On this version the following two socket options are enabled: The only protocol level supported in this version is SOL_SOCKET (level).
  1. SOCKOPT_RECV_TIMEOUT (optname) SOCKOPT_RECV_TIMEOUT configures recv and recvfrom timeout in milliseconds. In that case optval should be pointer to unsigned long.
  2. SOCKOPT_NONBLOCK (optname). sets the socket non-blocking mode on or off. In that case optval should be SOCK_ON or SOCK_OFF (optval).
See Also
getsockopt
Examples:
mqtt_wifi_subscriber.c, and wifi_tcp_server.c.
int socket ( long  domain,
long  type,
long  protocol 
)

create an endpoint for communication The socket function creates a socket that is bound to a specific transport service provider. This function is called by the application layer to obtain a socket handle.

socket

Parameters
domainselects the protocol family which will be used for communication. On this version only AF_INET is supported
typespecifies the communication semantics. On this version only SOCK_STREAM, SOCK_DGRAM, SOCK_RAW are supported
protocolspecifies a particular protocol to be used with the socket IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW are supported.
Returns
On success, socket handle that is used for consequent socket operations. On error, -1 is returned.
Examples:
mqtt_wifi_publisher.c, mqtt_wifi_subscriber.c, wifi_tcp_client.c, wifi_tcp_client_server.c, and wifi_tcp_server.c.