NI XNET IP Stack Functions

IP Stack Functions

• nxIpStackClear
• nxIpStackCreate
• nxIpStackFreeInfo
• nxIpStackGetInfo
• nxIpStackOpen
• nxIpStackGetAllStacksInfoStr
• nxIpStackFreeAllStacksInfoStr
• nxIpStackWaitForInterface

nxIpStackClear

Purpose

Clears (closes) the IP Stack.

Format

nxStatus_t nxIpStackClear ( nxIpStackRef_t stackRef);

Inputs

nxIpStackRef_t stackRef: The reference to the IP Stack to clear. This session reference is returned from nxIpStackCreate.

Outputs

Return Value

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

nxIpStackCreate

Purpose

Creates an IP stack to use for TCP and/or UDP communication.

Format

nxStatus_t nxIpStackCreate ( const char * stackName, const char * config, nxIpStackRef_t * stackRef);

Inputs

const char * stackName: The name that uniquely identifies the stack. The syntax for this name allows some special characters, such as space ( ). Invalid characters include forward slash (/), backslash (), period (.), and tab (\t). The name is not case sensitive. If you do not enter a value for StackName, NI-XNET generates a name to ensure that each stack is unique.

const char * config: The configuration of the IP Stack as a JSON string. For a list of features supported in the configuration, refer to Supported Features.

Outputs

nxIpStackRef_t stackRef: The reference to the created IP Stack. This session reference is used with subsequent functions for the IP Stack (for example, to obtain runtime info), TCP Socket, and UDP Socket.

Return Value

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error. If an error is returned, nxgetlasterrorstr can be used to obtain detailed information about potential problems with the IP Stack configuration.

Description

The IP Stack enables you to create an implementation of the TCP/IP protocol suite for TCP and UDP communication, independent from the limitations of the IP stack native to the operating system.

National Instruments installs documentation for the XNET IP Stack configuration string. The configuration string uses JSON format, and the formal documentation is provided as a JSON schema file. The JSON schema file is supported by a variety of online tools, and in addition to formally describing each field, it can be used to validate your customized JSON configuration string for correctness. To find the XNET IP Stack JSON schema, select Start»National Instruments»NI-XNET Documentation.

nxIpStackFreeInfo

Purpose

Frees the memory returned from nxIpStackGetInfo. Always call this function when you are finished with the stack information to avoid memory leaks.

Format

nxStatus_t nxIpStackFreeInfo ( nxVirtualInterface_t* firstVirtualInterface);

Inputs

nxVirtualInterface_t* firstVirtualInterface: The pointer to the virtual interface returned from nxIpStackGetInfo.

Outputs

Return Values

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

nxIpStackGetInfo

Purpose

Gets runtime information for an XNET IP Stack.

Format

nxStatus_t nxIpStackGetInfo ( nxIpStackRef_t StackRef, u32 infoID nxVirtualInterface_t** firstVirtualInterface);

Inputs

nxStackRef_t StackRef: The reference to the XNET IP Stack.

infoID: Always pass nxIPSTACK_INFO_ID to this parameter. This identifies the struct typedefs to return.

Outputs

Return Values

nxVirtualInterface_t** firstVirtualInterface: A struct with a pointer to the virtual interface. Use next pointers to go from one virtual interface to the next.

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

Description

The organization of this information is similar to the configuration passed into nxIpStackCreate, but this function provides runtime information that does not exist in that configuration. For example, if the configuration specifies using the link-local addressing protocol to acquire an IP address, this function's runtime information returns the actual IP address that was acquired using link-local addressing.

nxIpStackOpen

Purpose

Opens a reference to an IP Stack that has already been created. This may include stacks opened in a different process.

Format

nxStatus_t nxIpStackOpen ( const char * stackName, nxIpStackRef_t * stackRef);

Inputs

const char * stackName: The same stackName used with nxIpStackCreate.

Outputs

nxIpStackRef_t * stackRef: Returns the reference to the opened IP Stack. Pass this value to other functions that use an IP Stack reference.

Return Value

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

Description

After an IP Stack is created using nxIpStackCreate, the IP Stack is available for use by multiple processes. The IP Stack maintains a count of the number of times it is created and/or opened, so that it only closes after you call nxIpStackClear that number of times or all owning processes exit.

nxIpStackGetAllStacksInfoStr

Purpose

Gets runtime information for all XNET IP stacks active on the system. The information is returned in JSON or plain text format.

Format

nxStatus_t nxIpStackGetAllStacksInfoStr ( uint32_t formatType, char** info);

Inputs

nxIPSTACK_INFO_STR_FORMAT_JSON or nxIPSTACK_INFO_STR_FORMAT_TEXT: XNET IP Stack information in JSON plain text format.

Note  To parse the JSON string, use the schema in the following directory as an example for reference: C:\Users\Public\Documents\National Instruments\NI-XNET\Documentation\xnetStackInfoExampleSimple.json

Outputs

info: A pointer to the string containing the XNET IP Stacks information.

Return Values

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

nxIpStackFreeAllStacksInfoStr

Purpose

Frees the memory returned from nxIpStackGetAllStacksInfoStr. Always call this function when you are finished with the stacks information to avoid memory leaks.

Format

void nxIpStackFreeAllStacksInfoStr( char* info);

Inputs

Info: The pointer to the string returned from nxIpStackGetAllStacksInfoStr.

nxIpStackWaitForInterface

Purpose

Waits for interface(s) in the IP Stack to be ready for communication.

Format

nxStatus_t nxIpStackWaitForInterface ( nxIpStackRef_t stackRef, const char * localInterface, i32 timeoutMs);

Inputs

nxIpStackRef_t stackRef: The reference to the IP Stack.

const char * localInterface: The specific virtual interface in the IP Stack on which to wait for configuration. If localInterface is empty (default), this function waits for all virtual interfaces in the IP Stack to successfully configure. If localInterface is not empty, this function waits for a specific virtual interface. The virtual interface is identified using one of the following (as returned from nxIpStackGetInfo):

• virtual interface name (recommended)
• string that represents the decimal value of ifIndex
• unicast IP address from the IP address list

i32 timeoutMs: The time, in milliseconds, that the function waits to complete before returning a timeout error. The default is 60,000 ms. Pass a value of -1 to wait indefinitely.

Outputs

Return Value

nxStatus_t

The error code the function returns in the event of an error or warning. A value of 0 indicates success. A positive value indicates a warning. A negative value indicates an error.

Description

If an interface in the IP Stack acquires its unicast IP address dynamically (for example, using link-local addressing), it can take time for this acquisition to complete after creation of the IP Stack. This function enables the application to wait for an interface to be completely configured before creating sockets.