Link Search Menu Expand Document

Net System Service Interface

Table of contents

  1. Data Types and Constants Summary
  2. Initialization functions Summary
  3. Status functions Summary
  4. Setup functions Summary
  5. Data Exchange functions Summary
  6. Data Types and Constants
    1. SYS_NET_INTF_WIFI
    2. SYS_NET_INTF_ETHERNET
    3. SYS_NET_MODE_CLIENT
    4. SYS_NET_MODE_SERVER
    5. SYS_NET_MAX_HOSTNAME_LEN
    6. SYS_NET_IP_PROT_UDP
    7. SYS_NET_IP_PROT_TCP
    8. SYS_NET_MAX_NUM_OF_SOCKETS
    9. SYS_NET_DEFAULT_TLS_ENABLE
    10. SYS_NET_DEFAULT_AUTO_RECONNECT
    11. SYS_NET_DEFAULT_NET_INTF
    12. NET_CFG
    13. NET_DATA
    14. SYS_NET_Config
    15. SYS_NET_STATUS
    16. SYS_NET_EVENT
    17. SYS_NET_CTRL_MSG
    18. SYS_NET_RESULT
  7. Initialization functions
    1. SYS_NET_Initialize
    2. SYS_NET_Deinitialize
  8. Status functions
    1. SYS_NET_GetStatus
  9. Setup functions
    1. SYS_NET_Open
    2. SYS_NET_Close
    3. SYS_NET_Task
    4. SYS_NET_CtrlMsg
    5. SYS_NET_SetConfigParam
  10. Data Exchange functions
    1. SYS_NET_SendMsg
    2. SYS_NET_RecvMsg
    3. SYS_NET_CALLBACK

Data Types and Constants Summary

Name Description
SYS_NET_INTF_WIFI Net Socket Intf - Wifi
SYS_NET_INTF_ETHERNET Net Socket Intf - Ethernet
SYS_NET_MODE_CLIENT Net Socket Mode - Client
SYS_NET_MODE_SERVER Net Socket Mode - Server
SYS_NET_MAX_HOSTNAME_LEN Max Host Name Length
SYS_NET_IP_PROT_UDP Ip Protocol Mode - UDP
SYS_NET_IP_PROT_TCP Ip Protocol Mode - TCP
SYS_NET_MAX_NUM_OF_SOCKETS Number of Instances Supported by the NET System Service
SYS_NET_DEFAULT_TLS_ENABLE Default Values for TLS - False
SYS_NET_DEFAULT_AUTO_RECONNECT Default Values for Auto Reconnect - True
SYS_NET_DEFAULT_NET_INTF Default Values for Interface - 0 (Wifi)
NET_CFG AppDebug Flow for the Logs - Configuration
NET_DATA AppDebug Flow for the Logs - Data
SYS_NET_Config Used for passing on the configuration related to the Net Socket that needs
SYS_NET_STATUS Identifies the current status of the Sys Net Instance.
SYS_NET_EVENT Identifies the event type for which the User Callback is called.
SYS_NET_CTRL_MSG Identifies the control message for which the User has called the SYS_NET_CtrlMsg().
SYS_NET_RESULT Identifies the return values for the Sys Net APIs.

Initialization functions Summary

Name Description
SYS_NET_Initialize Returns success/ failure for initialization of data structures of the NET service
SYS_NET_Deinitialize Deinitialization of data structures of the NET service

Status functions Summary

Name Description
SYS_NET_GetStatus Returns System NET instance status.

Setup functions Summary

Name Description
SYS_NET_Open Opens a new NET System Service instance.
SYS_NET_Close Deinitializes the specific instance of the NET System service
SYS_NET_Task Executes the SYS NET service state machine for the instance
SYS_NET_CtrlMsg Returns success/ failure for the disconnect/ reconnect operation asked by the user.
SYS_NET_SetConfigParam Returns success on setting a configuration parameter for Net System Service.

Data Exchange functions Summary

Name Description
SYS_NET_SendMsg Returns No of Bytes sent to peer using the System NET instance.
SYS_NET_RecvMsg Returns No of Bytes received from peer using the System NET instance.
SYS_NET_CALLBACK Pointer to a Net system service callback function.

Data Types and Constants

SYS_NET_INTF_WIFI

Summary

Net Socket Intf - Wifi

Remarks

None.

#define SYS_NET_INTF_WIFI 0			// Wifi Intf Value

SYS_NET_INTF_ETHERNET

Summary

Net Socket Intf - Ethernet

Remarks

None.

#define SYS_NET_INTF_ETHERNET 1			// Ethernet Intf Value

SYS_NET_MODE_CLIENT

Summary

Net Socket Mode - Client

Remarks

None.

#define SYS_NET_MODE_CLIENT 0			// Client Mode Value

SYS_NET_MODE_SERVER

Summary

Net Socket Mode - Server

Remarks

None.

#define SYS_NET_MODE_SERVER 1			// Server Mode Value

SYS_NET_MAX_HOSTNAME_LEN

Summary

Max Host Name Length

Remarks

None.

#define SYS_NET_MAX_HOSTNAME_LEN 	256 	// Max Host Name Length

SYS_NET_IP_PROT_UDP

Summary

Ip Protocol Mode - UDP

Remarks

None.

#define SYS_NET_IP_PROT_UDP 0			// UDP - Ip Protocol Value

SYS_NET_IP_PROT_TCP

Summary

Ip Protocol Mode - TCP

Remarks

None.

#define SYS_NET_IP_PROT_TCP 1			// TCP - Ip Protocol Value

SYS_NET_MAX_NUM_OF_SOCKETS

Summary

Number of Instances Supported by the NET System Service

Remarks

None.

#define SYS_NET_MAX_NUM_OF_SOCKETS 2			// umber of Instances Supported by the NET System Service

SYS_NET_DEFAULT_TLS_ENABLE

Summary

Default Values for TLS - False

Remarks

None.

#define SYS_NET_DEFAULT_TLS_ENABLE 0	// TLS Disabled by default

SYS_NET_DEFAULT_AUTO_RECONNECT

Summary

Default Values for Auto Reconnect - True

Remarks

None.

#define SYS_NET_DEFAULT_AUTO_RECONNECT 1	// Auto Reconnect Enabled by default

SYS_NET_DEFAULT_NET_INTF

Summary

Default Values for Interface - 0 (Wifi)

Remarks

None.

#define SYS_NET_DEFAULT_NET_INTF 0	// Interface 0 by default

NET_CFG

Summary

AppDebug Flow for the Logs - Configuration

Remarks

None.

#define NET_CFG 0x1					// App Debug Print Flows - CFG

NET_DATA

Summary

AppDebug Flow for the Logs - Data

Remarks

None.

#define NET_DATA 0x2					// App Debug Print Flows - DATA

SYS_NET_Config

Summary

Used for passing on the configuration related to the Net Socket that needs to be opened via the Sys Net Service

Remarks

None.

typedef struct {
// Net Socket Mode to Open - SYS_NET_MODE_CLIENT(0)/ SYS_NET_MODE_SERVER(1)
uint8_t mode;

// WiFi or Eth Interface to be used for Opening the socket
uint8_t	intf;

// Net Server Port
uint16_t port;

// Reconnect in case of disconnection happening - 1(Reconnect Enabled)/ 0(Reconnect Disabled)
bool enable_reconnect;

// Net Socket with 1(TLS Enabled)/ 0(TLS Disabled)
bool enable_tls;

// Socket IP Protocol - SYS_NET_IP_PROT_UDP(0) or SYS_NET_IP_PROT_TCP(1)
uint8_t ip_prot;

// Host Name - could have the server name or IP
char	host_name[SYS_NET_MAX_HOSTNAME_LEN];
} SYS_NET_Config;

SYS_NET_STATUS

Summary

Identifies the current status of the Sys Net Instance.

Remarks

None.

typedef enum {
// Net Instance is Idle/ Not in Use
SYS_NET_STATUS_IDLE = 0,

// Lower Layer is Down
SYS_NET_STATUS_LOWER_LAYER_DOWN,

// Resolving DNS of NET Server for the Client to connect
SYS_NET_STATUS_RESOLVING_DNS,

// Net Server IP Available for the Client to connect
SYS_NET_STATUS_DNS_RESOLVED,

// Net Server Awaiting Connection
SYS_NET_STATUS_SERVER_AWAITING_CONNECTION,

// Net Client connecting to Server
SYS_NET_STATUS_CLIENT_CONNECTING,

// Net Client Waiting for SNTP Time Stamp
SYS_NET_STATUS_WAIT_FOR_SNTP,

// Net Client Starting TLS Negotiations
SYS_NET_STATUS_TLS_NEGOTIATING,

// Net Instance TLS Negotiation Failed
SYS_NET_STATUS_TLS_NEGOTIATION_FAILED,
// Net Instance connected to the peer
SYS_NET_STATUS_CONNECTED,

// Net Instance Failed to open socket
SYS_NET_STATUS_SOCK_OPEN_FAILED,

// Net Instance Failed to Resolve DNS
SYS_NET_STATUS_DNS_RESOLVE_FAILED,

// Net Instance in disconnected state
SYS_NET_STATUS_DISCONNECTED,

// Net Instance received FIN from peer
SYS_NET_STATUS_PEER_SENT_FIN,
} SYS_NET_STATUS;

SYS_NET_EVENT

Summary

Identifies the event type for which the User Callback is called.

Remarks

None.

typedef enum {
// NET Socket connected to Peer
SYS_NET_EVNT_CONNECTED = 0,

// NET Socket disconnected
SYS_NET_EVNT_DISCONNECTED,

// Received Data on NET Socket connected to Peer
SYS_NET_EVNT_RCVD_DATA,

// SSL Negotiation Failed
SYS_NET_EVNT_SSL_FAILED,

// DNS Resolve Failed
SYS_NET_EVNT_DNS_RESOLVE_FAILED,

// Socket Open Failed
SYS_NET_EVNT_SOCK_OPEN_FAILED,
} SYS_NET_EVENT;

SYS_NET_CTRL_MSG

Summary

Identifies the control message for which the User has called the SYS_NET_CtrlMsg().

Remarks

None.

typedef enum {
// NET Socket should reconnect to Peer, the User is expected to pass pointer to SYS_NET_Config for the configuration of the new Connection.
SYS_NET_CTRL_MSG_RECONNECT = 0,

// NET Socket disconnect request from the user
SYS_NET_CTRL_MSG_DISCONNECT,
} SYS_NET_CTRL_MSG;

SYS_NET_RESULT

Summary

Identifies the return values for the Sys Net APIs.

Remarks

None.

typedef enum {
// Success
SYS_NET_SUCCESS = 0,

// Failure
SYS_NET_FAILURE = -1,

// Sys NET Service Down
SYS_NET_SERVICE_DOWN = -2,

// Enough space not available in the transmit buffer to send the message. Application should try again later
SYS_NET_PUT_NOT_READY = -3,

// Sys NET No Data Available for receiving
SYS_NET_GET_NOT_READY = -4,

// Sys NET Semaphore Operation of Take/ Release Failed
SYS_NET_SEM_OPERATION_FAILURE = -5,

// Sys NET Invalid Handle
SYS_NET_INVALID_HANDLE = -6,

} SYS_NET_RESULT;

Initialization functions

SYS_NET_Initialize

Function

int32_t SYS_NET_Initialize()

Summary

Returns success/ failure for initialization of data structures of the NET service

Description

This function is used for initializing the data structures of the NET service and is called from within the System Task.

Returns

SYS_NET_SUCCESS - Indicates the data structures were initialized successfully

SYS_NET_FAILURE - Indicates that it failed to initialize the data structures.

Example

if( SYS_NET_Initialize() == SYS_NET_SUCCESS)
{
}

Remarks

If the Net system service is enabled using MHC, then auto generated code will take care of Net System Service initialization.

SYS_NET_Deinitialize

Function

void SYS_NET_Deinitialize()

Summary

Deinitialization of data structures of the NET service

Description

This function is used for freeing the allocated data structures for the NET service.

Example

SYS_NET_Deinitialize()

Remarks

None

Status functions

SYS_NET_GetStatus

Function

SYS_NET_STATUS SYS_NET_GetStatus ( SYS_MODULE_OBJ object )

Summary

Returns System NET instance status.

Description

This function returns the current status of the System NET instance.

Precondition

SYS_NET_Open should have been called before calling this function

Parameters

object - SYS NET object handle, returned from SYS_NET_Open

Returns

SYS_NET_STATUS

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.
if (SYS_NET_GetStatus (objSysNet) == SYS_NET_STATUS_SERVER_AWAITING_CONNECTION)
{
// NET system service is initialized and the NET server is ready to accept new connection.
}

Remarks

None.

Setup functions

SYS_NET_Open

Function

SYS_MODULE_OBJ SYS_NET_Open (SYS_NET_Config *cfg,
SYS_NET_CALLBACK Net_cb,
void *cookie)

Summary

Opens a new NET System Service instance.

Description

This function opens the instance of the NET System Service.

Parameters

cfg - Configuration for which the NET Socket needs to be opened
Net_cb - Function pointer to the Callback to be called in case of an event
cookie - Cookie passed as one of the params in the Callback which was registered by the user in SYS_NET_Open
Returns

Returns: If successful, returns a valid handle to an object. Otherwise, it returns SYS_MODULE_OBJ_INVALID.

Example

SYS_NET_Config 	g_NetServCfg;
SYS_MODULE_OBJ 		g_NetServHandle;

memset(&g_NetServCfg, 0, sizeof(g_NetServCfg));
g_NetServCfg.mode = SYS_NET_MODE_CLIENT;
strcpy(g_NetServCfg.host_name, APP_HOST_NAME);
g_NetServCfg.port = APP_HOST_PORT;
g_NetServCfg.enable_tls = 0;
g_NetServCfg.ip_prot = SYS_NET_IP_PROT_UDP;
g_NetServHandle = SYS_NET_Open(&g_NetServCfg, NetServCallback, 0);
if (g_NetServHandle == SYS_MODULE_OBJ_INVALID)
{
// Handle error
}

Remarks

This routine should be called everytime a user wants to open a new NET socket

SYS_NET_Close

Function

void SYS_NET_Close ( SYS_MODULE_OBJ object )

Summary

Deinitializes the specific instance of the NET System service

Description

This function deinitializes the specific module instance disabling its operation. Resets all of the internal data structures and fields for the specified instance to the default settings.

Precondition

The SYS_NET_Open function should have been called before calling this function.

Parameters

object - SYS NET object handle, returned from SYS_NET_Open

Returns

None.

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.

SYS_NET_Close (objSysNet);

Remarks

Once the Open operation has been called, the Close operation must be called before the Open operation can be called again.

SYS_NET_Task

Function

void SYS_NET_Task(SYS_MODULE_OBJ obj)

Summary

Executes the SYS NET service state machine for the instance

Description

This function ensures that the Net system service is able to execute its state machine to process any messages and invoke the user callback for any events.

Precondition

SYS_NET_Open should have been called before calling this function

Parameters

obj - SYS NET object handle, returned from SYS_NET_Open

Returns

None

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.
while(1)
{
...
SYS_NET_Task(objSysNet);
...
}

SYS_NET_CtrlMsg

Function

int32_t SYS_NET_CtrlMsg(SYS_MODULE_OBJ obj, SYS_NET_CTRL_MSG msg_type, void *data, uint16_t len)

Summary

Returns success/ failure for the disconnect/ reconnect operation asked by the user.

Description

This function is used for disconnecting or reconnecting to the peer.

Precondition

SYS_NET_Open should have been called.

Parameters

obj - SYS NET object handle, returned from SYS_NET_Open
msg_type - valid Msg Type SYS_NET_CTRL_MSG

data - valid data buffer pointer based on the Msg Type - NULL for DISCONNECT, Pointer to SYS_NET_Config for RECONNECT
len - length of the data buffer the pointer is pointing to

Returns

SYS_NET_SUCCESS - Indicates that the Request was catered to successfully

SYS_NET_FAILURE - Indicates that the Request failed

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.
if( SYS_NET_CtrlMsg(objSysNet, SYS_NET_CTRL_MSG_DISCONNECT, NULL, 0) == SYS_NET_SUCCESS)
{
}

Remarks

None.

SYS_NET_SetConfigParam

Function

int32_t SYS_NET_SetConfigParam(SYS_MODULE_OBJ obj, uint32_t paramType, void *data)

Summary

Returns success on setting a configuration parameter for Net System Service.

Description

This function is currently used for enabling/ disabling the Auto Reconnect feature for the Net Socket.

Precondition

SYS_NET_Open should have been called.

Parameters

obj - SYS NET object handle, returned from SYS_NET_Open
paramType - Reserved for future use
data - 0/ 1 currently used only for enabling/ disabling the auto reconnect feature

Returns

SYS_NET_SUCCESS - Indicates that the Request was catered to successfully

Example

bool auto_reconnect = true;
// Handle "objSysNet" value must have been returned from SYS_NET_Open.
if( SYS_NET_SetConfigParam(objSysNet, 0, &auto_reconnect) == SYS_NET_SUCCESS)
{
}

Remarks

None.

Data Exchange functions

SYS_NET_SendMsg

Function

int32_t SYS_NET_SendMsg(SYS_MODULE_OBJ obj, uint8_t *buffer, uint16_t len)

Summary

Returns No of Bytes sent to peer using the System NET instance.

Description

This function returns the number of bytes transmitted to the peer.

Precondition

SYS_NET_Open should have been called.

Parameters

object - SYS NET object handle, returned from SYS_NET_Open
data - valid data buffer pointer
len - length of the data to be transmitted

Returns

SYS_NET_SERVICE_DOWN - Indicates that the System NET instance is not connected to the peer

SYS_NET_PUT_NOT_READY - Indicates that the System NET instance Put is NOT ready

SYS_NET_PUT_BUFFER_NOT_ENOUGH - Indicates that the System NET instance cannot transmit as the available buffer is less than the bytes to be transmitted

Positive Non-Zero - Indicates the number of bytes transmitted to the peer

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.
while(SYS_NET_SendMsg(objSysNet, "hello", 5) <= 0);

Remarks

None.

SYS_NET_RecvMsg

Function

int32_t SYS_NET_RecvMsg(SYS_MODULE_OBJ obj, void *data, uint16_t len)

Summary

Returns No of Bytes received from peer using the System NET instance.

Description

This function returns the number of bytes received from the peer.

Precondition

SYS_NET_Open should have been called.

Parameters

obj - SYS NET object handle, returned from SYS_NET_Open
data - valid data buffer pointer
len - length of the data to be transmitted

Returns

SYS_NET_SERVICE_DOWN - Indicates that the System NET instance is not connected to the peer

SYS_NET_GET_NOT_READY - Indicates that the System NET instance No Data to GET

Positive Non-Zero - Indicates the number of bytes received from the peer, which may be less than the “len” of the buffer passed as the param.

Example

// Handle "objSysNet" value must have been returned from SYS_NET_Open.
int32_t len = 32;
uint8_t buffer[32] = {0};
len = SYS_NET_RecvMsg(objSysNet, buffer, len);
if(len > 0)
{
}

Remarks

None.

SYS_NET_CALLBACK

Function

void (*SYS_NET_CALLBACK) (uint32_t event, void *data, void* cookie)

Summary

Pointer to a Net system service callback function.

Description

This data type defines a pointer to a Net service callback function, thus defining the function signature. Callback functions may be registered by clients of the net service when opening a Net socket via the Initialize call.

Precondition

Is a part of the Net service initialization using the SYS_NET_Open function.

Parameters

event - An event (SYS_NET_EVENT) for which the callback was called.
data - Data (if any) related to the Event
cookie - A context value, returned untouched to the client when the callback occurs.

Returns

None.

Example

void NetServCallback(uint32_t event, void *data, void* cookie, )
{
switch(event)
{
case SYS_NET_EVNT_CONNECTED:
{
SYS_CONSOLE_PRINT("NetServCallback(): Status UP");
while(SYS_NET_SendMsg(g_NetServHandle, "hello", 5) == 0);
break;
}

case SYS_NET_EVNT_DISCONNECTED:
{
SYS_CONSOLE_PRINT("NetServCallback(): Status DOWN");
break;
}

case SYS_NET_EVNT_RCVD_DATA:
{
int32_t len = 32;
uint8_t buffer[32] = {0};
len = SYS_NET_RecvMsg(g_NetServHandle, buffer, len);
SYS_CONSOLE_PRINT("NetServCallback(): Data Rcvd = %s", buffer);
break;
}
}
}

Remarks

None.



Copyright © 2020 Microchip Technology.