API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

ISOCKET

Brew Release
Brew MP 1.0.2
See Also
None.
Description
The ISocket Interface provides methods to connect, transmit and receive data over, and close TCP and UDP sockets that are opened using the INETMGR_OpenSocket().
In new Brew versions, ISockPort replaces ISocket and is recommended for use.
NOTE: Your application must have a privilege level of Network or All to be able to invoke the functions in this interface.
The function ISOCKET_Connect() is called immediately after opening a TCP socket. If the network subsystem (physical layer, RLP and PPP) of the device is not active, this function first establishes the necessary lower-layer protocol connections. For TCP sockets, ISOCKET_Connect() then sets up a TCP connection to the specified IP address and port number. For UDP sockets, the caller may specify the destination IP address and port numbers for each read or write operation, thereby allowing data to be sent to and received from multiple IP addresses and ports.
After the TCP socket has been connected, read and write operations may be used to exchange data over it. All data transfer operations are non-blocking and asynchronous. the callback functions are used to notify the caller of the availability of socket for read or write operations. The caller can use ISOCKET_Readable() to provide the address of a callback function that must be invoked when there is data available to read. Similarly, ISOCKET_Writeable() registers the callback function that gets invoked when the socket is available for writing. Callback functions are invoked whenever BREW detects any error conditions on the socket that require the application using this interface to take action.
The function ISOCKET_Cancel() is used to cancel a pending callback operation, thereby preventing the application from receiving notification when there is a change in the status of the socket it is waiting on.
The functions ISOCKET_Read() and ISOCKET_Write() are used for reading data from and writing data to TCP sockets. If the read or write do not make progress, ISOCKET_Read() and ISOCKET_Write()return an indication that blocking has occurred. The caller can then use ISOCKET_Readable() or ISOCKET_Writeable() to arrange to be notified when blocking is no longer present. If the number of bytes actually read or written is less than the number requested, repeat calls to ISOCKET_Read() or ISOCKET_Write() to complete the data transfer.
The functions ISOCKET_ReadV() and ISOCKET_WriteV() are used to receive and send data on TCP sockets when the application uses multiple, non-contiguous buffers for reading and writing. In place of the single buffer pointer supplied as a parameter to ISOCKET_Read() and ISOCKET_Write(), ISOCKET_ReadV() and ISOCKET_WriteV() each take an array of buffer descriptors as input, with each array element specifying the length in bytes and starting address of a buffer. These functions attempt to transfer an amount of data equal to the sum of the buffer lengths, starting with the first buffer in the array.
The functions ISOCKET_RecvFrom() and ISOCKET_SendTo() are used to exchange data over UDP sockets. Both these functions allow data to be sent to and received from multiple IP addresses and port numbers. As with TCP sockets, the application may call ISOCKET_Readable() or ISOCKET_Writeable() to designate a callback function if the read or write operation does not make progress immediately
The function ISOCKET_Bind() associates a local port number with a socket (if an application does not call this function before ISOCKET_Connect(), or ISOCKET_SendTo() a default value is used for the local port number).
The functions ISOCKET_Listen() and ISOCKET_Accept() are used to implement a server that can accept incoming TCP connections.
The function ISOCKET_GetLastError() returns the error code for the last error detected by a function in the ISocket Interface. In cases where such a function returns something other than success, ISOCKET_GetLastError() provides more detailed information about why the function failed to perform its task.
The function ISOCKET_GetPeerName() returns the IP address and port number of the entity with which data was most recently exchanged on the socket.
The function ISOCKET_GetSockName() returns the IP address and port number of the local socket.
The functions ISOCKET_GetOpt() and ISOCKET_SetOpt() retrieve and specify optional parameters for a socket and/or the underlying network stack. See the AEESockOpt documentation for the supported options.
Receiving multicast datagrams is enabled by setting the AEE_IP_ADD_MEMBERSHIP socket option. Note that multicast is only supported on a small subset of devices and carrier networks; please verify support before making use of this feature.
After completion of data transfer, a call to ISOCKET_Shutdown() or ISOCKET_Close() gracefully closes a TCP connection.
A call to ISOCKET_Release() also closes any socket connection and releases the ISocket Interface and frees the associated resources.
ISOCKET_IOCtl() allows some control over the behavior of an ISocket, i.e. connect time-outs.
See also ISOURCEUTIL_SourceFromSocket().
Usage
To use the socket services 1. Call ISHELL_CreateInstance() to create an instance of the INetMgr Interface. 2. Call INETMGR_OpenSocket() to create an instance of the ISocket Interface (to open a TCP or UDP socket). 3. Call ISOCKET_Connect() to establish a TCP socket connection with the network entity with which the application communicates. 4. Use the functions in the ISocket Interface to operate on the socket.
To read or write data over the socket 1. Call the relevant (TCP/UDP, single/multiple I/O buffers) read or write functions described above. 2. If the function returns a blocking indication, call ISOCKET_Readable() or ISOCKET_Writeable() to attempt the operation at a later time. 3. If less than the requested number of bytes were transferred, call the read or write function again to effect the transfer of the remaining data. 4. Repeat steps 1-3, until all of your data has been transferred. 5. Call ISOCKET_Bind() to specify the socket's local port number. 6. Call ISOCKET_GetPeerName() to obtain the remote IP address and port number of the connected TCP socket. 7. Call ISOCKET_Release() to close the socket after completing the data transfer. 8. Call INETMGR_Release() to release the INetMgr Interface instance.