User API

Core system functions to be called by user. More...

Functions
netStatus	netInitialize (void)
	Initialize Network Component and interfaces. [not_thread-safe].
netStatus	netUninitialize (void)
	De-initialize Network Component and interfaces. [not_thread-safe].
const char *	netSYS_GetHostName (void)
	Retrieve localhost name. [thread-safe].
netStatus	netSYS_SetHostName (const char *hostname)
	Set localhost name. [thread-safe].

Description

Core system functions to be called by user.

The network system functions provide the core mechanisms for initializing, managing, and handling events within the network stack. These functions support essential operations such as initialization, configuration, error management, and shutdown procedures. Include a callback function to handle critical, unrecoverable errors.

Function Documentation

netInitialize()

netStatus netInitialize ( void )

extern

Initialize Network Component and interfaces. [not_thread-safe].

Returns

status code that indicates the execution status of the function.

The function netInitialize initializes the Network Core's system resources, protocols, threads and applications. Since the function also creates RTOS objects, the RTOS must be previously initialized.

Note

You must call the function at system start-up to properly initialize the networking environment.

Possible netStatus return values:

• netOK: Network Core initialized successfully.
• netError: Failed to initialize the Network Core.

Code Example

int main (void) {
 
  init_hal ();
  // Initialize the Network Core 
  netInitialize ();
   ..
}

netSYS_GetHostName()

const char * netSYS_GetHostName ( void )

extern

Retrieve localhost name. [thread-safe].

Returns

pointer to localhost name, a null-terminated string.

The function netSYS_GetHostName returns the name of the local host. The name is set with NET_HOST_NAME in the Net_Config.h, and can be changed at runtime.

Code Example

printf ("Localhost name is %s\n", netSYS_GetHostName ());

netSYS_SetHostName()

netStatus netSYS_SetHostName ( const char * hostname )

extern

Set localhost name. [thread-safe].

Parameters

[in]

hostname

new localhost name, a null-terminated string.

Returns

status code that indicates the execution status of the function.

The function netSYS_SetHostName sets the name of the local host. Default name is set with NET_HOST_NAME in the Net_Config.h, and can be changed at runtime.

The argument hostname is a pointer to the localhost name that is to be set, which is a null-terminated string. The function copies the content of the hostname to the localhost name. The maximum length of the hostname string is limited to 15 characters.

Possible netStatus return values:

• netOK: Host name successfully set.
• netInvalidParameter: Invalid hostname provided.

Note

When the function ends, the content of hostname becomes irrelevant and may be discarded.

Code Example

netSYS_SetHostName ("MCB1800");
printf ("Localhost name is %s\n", netSYS_GetHostName ());

netUninitialize()

netStatus netUninitialize ( void )

extern

De-initialize Network Component and interfaces. [not_thread-safe].

Returns

status code that indicates the execution status of the function.

The function netUninitialize de-initializes the Network Core's system resources, protocols, threads and applications. Network drivers are de-initialized and powered off. After calling this function the networking environment is in initial state. To use it again, you must call netInitialize function again.

Possible netStatus return values:

• netOK: Network Core de-initialized successfully.
• netError: Failed to de-initialize the Network Core.

Code Example

int main (void) {
 
  init_hal ();
  // Initialize the Network Core 
  netInitialize ();
   ..
  // Uninitialize the Network Core
  netUninitialize (); 
}