Transport Layer User API

 1int8_t create_socket(int8_t type);
 2
 3/*
 4
 5This function creates a socket of a given type and returns it's descriptor
 6
 7    PARAMS:        type: The type of the socket. Currently only SOCK_DGRAM is supported
 8    RETURNS:    socket descriptor or NRK_ERROR otherwise
 9    ERROR NOS:    UNSUPPORTED_SOCK_TYPE if an invalid socket type is passed
10            NO_SOCKET_DESC_AVAILABLE if no descriptor is available
11    COMMENTS:    User API
12*/
 1uint8_t get_port_num(int8_t sock_num);
 2
 3/*
 4
 5This function can be used by an application to find the port number mapped to a given socket descriptor
 6
 7    PARAMS:        sock_num: The socket descriptor
 8    RETURNS:    the corresponding port number or INVALID_PORT if none exists / error
 9
10    ERROR NOS:    INVALID_ARGUMENT if the passed parameter is faulty
11            INVALID_SOCKET if a wrong socket number is passed
12            UNMAPPED_SOCKET if no socket/port mapping exists
13
14    Comments:    User API
15            A return value of INVALID_PORT could mean either an error has occurred or there 
16            does not exist any socket/port mapping. Check the error number to find out.
17*/ 
 1int8_t bind(int8_t sock_num, int16_t port);
 2/*
 3This function binds a given socket descriptor to a given port number
 4
 5    PARAMS:        sock_num: The socket number
 6            port:      The port number
 7
 8    RETURNS:    NRK_OK if the bind was successful
 9            NRK_ERROR if not
10
11    ERROR NOS:    INVALID_ARGUMENT when the passed paramters are faulty
12            INVALID_SOCKET if a wrong socket number is passed
13            PORT_UNAVAILABLE if the requested port number is already taken
14            NO_RX_BUFFERS_AVAILABLE if the system has run out of receive buffers
15            INVALID_CALL if bind() or set_rx_queue_size() was called earlier
16
17    COMMENTS:    User API
18*/
 1int8_t get_rx_queue_size(int8_t sock_num);
 2/*
 3This function returns the size of the rx queue associated with a given socket descriptor
 4
 5    PARAMS:        sock_num: The socket descriptor
 6    RETURNS:    size of the rx queue if no error is found, NRK_ERROR otherwise
 7
 8    ERROR NOS:    INVALID_ARGUMENT when the passed paramters are faulty
 9            INVALID_SOCKET if a wrong socket number is passed
10
11    COMMENTS:    User API. 
12            If no socket operation is performed on the passed socket descriptor prior
13            to this call, no rx buffers are set aside and hence 0 is returned
14*/    
 1int8_t set_rx_queue_size(int8_t sock_num, int8_t size);
 2/*
 3This function sets the size of the receive queue for a given socket descriptor
 4
 5    PARAMS:        size:    Size of the queue in units of number of transport layer segments
 6            sock_num: socket descriptor corresponding to the port for which the buffers
 7                are being requested
 8
 9    RETURNS:    actual number of rx buffers allocated. Usually this will equal 'size' but it 
10            may be less than 'size' if not enough buffers are available in the pool.
11
12    ERROR NOS:     INVALID_ARGUMENT when the passed parameters are faulty
13            INVALID_SOCKET if a wrong socket number is passed
14            NO_PORTS_AVAILABLE if bind() was not called previously 
15            and no ephemeral ports are available
16            NO_RX_BUFFERS_AVAILABLE if bind() was not called previously 
17            and no buffers are available
18
19    COMMENTS:    User API
20            This function can be called independently of bind(). Remember however that
21            3 things are essential for a socket description to be complete
22            1. a valid pid
23            2. a valid port
24            3. a receive queue of size at least 1
25
26*/ 
 1int8_t release_buffer(int8_t sock_num, uint8_t* ptr);
 2/* 
 3This function allows an application to return a receive buffer back to the buffer manager
 4
 5    PARAMS:        ptr: pointer to the buffer
 6            sock_num: socket descriptor corresponding to the port number to which the 
 7             receive buffer belongs 
 8
 9    RETURNS:    NRK_OK if the release is successful, NRK_ERROR otherwise
10
11    ERROR NOS:    INVALID_ARGUMENT when the passed parameters are faulty
12            INVALID_SOCKET if the wrong socket number is passed
13
14    COMMENTS:    User API
15            This function should be called when the application has finished processing
16            a received message or has copied the message to a application-local storage 
17            area
18*/ 
 1int8_t close_socket(int8_t sock_num);
 2/*
 3This function allows an application to close an existing opened socket
 4
 5        PARAMS:     sock_num: The socket descriptor
 6        RETURNS:    NRK_OK if the close operation is performed successfully, NRK_ERROR otherwise
 7
 8        ERROR NOS:    INVALID_ARGUMENT when the passed parameters are faulty
 9                INVALID_SOCKET if the wrong socket number is passed
10
11        COMMENTS: User API
12*/
 1int8_t is_port_associated(int16_t port);
 2/*
 3This function checks whether a given port number has been assigned to a socket or not 
 4
 5        PARAMS:        port: The port number
 6        RETURNS:     TRUE if a mapping exists, FALSE if a mapping does not exist, NRK_ERROR on error
 7
 8        ERROR NOS:    INVALID_ARGUMENT if the passed paramter is faulty        
 9        COMMENTS:     User API 
10*/
 1int8_t send(int8_t sock_num, uint8_t *ptr, int8_t len, int32_t dest_addr, int16_t dest_port, int8_t prio);
 2/*
 3This function can be used by the application task to send data to other nodes on the network
 4
 5    PARAMS:     ptr:           pointer to application task buffer
 6            len:         size of the message to be transmitted
 7            dest_addr:   address of destination node
 8            dest_port:   receiving port number of destination task
 9            prio:        priority of the message to be sent 
10
11    RETURNS:     NRK_OK if the message is queued successfully in the TX queue, 
12            NRK_ERROR otherwise
13
14    ERROR NOS:    INVALID_ARGUMENT if the passed paramters are faulty
15            INVALID_SOCKET if the wrong socket number is passed
16            NO_PORTS_AVAILABLE if this is the first operation to be performed on the socket and no ephemeral port number is  
17                        present
18            NO_RX_BUFFERS_AVAILABLE if this is the first operation to be performed on the socket and no receive buffers are 
19                        available
20            NO_TX_BUFFERS_AVAILABLE if the transmit queue of the system is full
21
22    COMMENTS:     User API
23            non-blocking, returns status code immediately. A return value of NRK_OK only means
24            that the message has been queued in the transmit queue. Look for the send_done signal
25            to find out when the message actually leaves the radio.
26*/
 1int8_t set_timeout(int8_t sock_num, int8_t secs, int8_t nano_secs);
 2/*
 3This functions allows an application task to set a timeout value on a given socket 
 4
 5    PARAMS:        sock_num: The socket descriptor
 6            secs, nano_secs: The timeout value
 7
 8    RETURNS:    NRK_OK if the timeout was regsitered correctly
 9            NRK_ERROR otherwise
10
11    ERROR NOS:    INVALID_ARGUMENT if the passed paramters are faulty
12            INVALID_SOCKET if the wrong socket number is passed 
13
14    Comments:    User API
15            You cannot pass a value of (0,0) as the timeout value. One or both of the 
16            paramters have to be positive integers. Use check_receive_queue() for a 
17            non-blocking receive()
18*/ 
 1uint8_t* receive(int8_t sock_num, int8_t *len, uint16_t *srcAddr, uint8_t *srcPort, int8_t *rssi);
 2/*
 3This function allows an application to receive a message along with network control information
 4from its socket
 5
 6    PARAMS:        sock_num: The socket descriptor
 7            len:      The network stack will put the length of the received message in this variable
 8            srcAddr:  The network stack will put the source address of the message in this variable
 9            srcPort:  The network stack will put the source port of the message in this variable 
10            rssi:      The network stack will put the signal strength with which the underlying
11                  packet was received in this variable
12
13    RETURNS:    pointer to the application payload
14            NULL if some error is encountered
15
16    ERROR NOS:    INVALID_ARGUMENT if the passed paramters are faulty
17            INVALID_SOCKET if a wrong socket number is passed
18            SOCKET_TIMEOUT if a timeout value is specified prior to this call and 
19            the timeout value expires
20
21    Comments:    User API
22            This function will block the task until a message arrives in its receive buffer
23            If you want to specify a maximum wait period, use set_timeout() prior to every such
24            receive() call.
25*/ 
 1int8_t check_receive_queue(int8_t sock_num);
 2/*
 3This function allows an application to check whether there is any message queued for it 
 4
 5    PARAMS:        sock_num: The socket descriptor
 6
 7    RETURNS:    number of queued messages (0 if the queue is empty)
 8            NRK_ERROR if some error is encountered during processing
 9
10    ERROR NOS:    INVALID_ARGUMENT if the passed paramter is faulty
11            INVALID_SOCKET if the wrong socket number is passed
12
13    Comments:    User API
14            Use this function if you want a non-blocking receive(). Call this first and if
15            this returns a positive integer, a subsequent receive() call will return the
16            queued message    immediately. 
17
18            NOTE: The number returned by this function corresponds to the number of queued
19            messages NOT yet read by the application.    If the application has not
20            released a buffer it receive()'d previously, that message is not included in
21            the count.
22*/ 
 1int8_t wait_until_send_done(int8_t sock_num);
 2/*
 3This function will block the task until a message enqueued by it previously is actually sent over 
 4the radio
 5
 6    PARAMS:        sock_num: The socket descriptor
 7    RETURNS:    NRK_OK if the 'send_done' signal wakes the task up
 8            NRK_ERROR if there is some error in processing OR timeout value when specified expires.
 9                        In this case, the error number is set to SOCKET_TIMEOUT
10
11    ERROR NOS:    INVALID_ARGUMENT if the passed parameter is faulty
12            INVALID_SOCKET if an incomplete socket descriptor is passed
13            SOCKET_TIMEOUT if a timeout value is specified prior to this call and 
14            the timeout value expires
15    Comments:    User API
16            If you want to specify a maximum wait period, use set_timeout() prior to every such
17            wait_until_send_done() call. The return value of NRK_ERROR could mean either that an 
18            error occured during processing or that the timeout expired. Check the error number
19            to find out
20*/