NI XNET IP Stack Functions - ni/grpc-device GitHub Wiki
- nxIpStackClear
- nxIpStackCreate
- nxIpStackFreeInfo
- nxIpStackGetInfo
- nxIpStackOpen
- nxIpStackGetAllStacksInfoStr
- nxIpStackFreeAllStacksInfoStr
- nxIpStackWaitForInterface
Clears (closes) the IP Stack.
nxStatus_t nxIpStackClear ( nxIpStackRef_t stackRef);
nxIpStackRef_t stackRef: The reference to the IP Stack to clear. This session reference is returned from nxIpStackCreate.
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.
Creates an IP stack to use for TCP and/or UDP communication.
nxStatus_t nxIpStackCreate ( const char * stackName, const char * config, nxIpStackRef_t * stackRef);
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.
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.
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.
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.
Frees the memory returned from nxIpStackGetInfo. Always call this function when you are finished with the stack information to avoid memory leaks.
nxStatus_t nxIpStackFreeInfo ( nxVirtualInterface_t* firstVirtualInterface);
nxVirtualInterface_t* firstVirtualInterface: The pointer to the virtual interface returned from nxIpStackGetInfo.
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.
Gets runtime information for an XNET IP Stack.
nxStatus_t nxIpStackGetInfo ( nxIpStackRef_t StackRef, u32 infoID nxVirtualInterface_t** firstVirtualInterface);
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.
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.
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.
Opens a reference to an IP Stack that has already been created. This may include stacks opened in a different process.
nxStatus_t nxIpStackOpen ( const char * stackName, nxIpStackRef_t * stackRef);
const char * stackName: The same stackName used with nxIpStackCreate.
nxIpStackRef_t * stackRef: Returns the reference to the opened IP Stack. Pass this value to other functions that use an IP Stack reference.
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.
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.
Gets runtime information for all XNET IP stacks active on the system. The information is returned in JSON or plain text format.
nxStatus_t nxIpStackGetAllStacksInfoStr ( uint32_t formatType, char** info);
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
info: A pointer to the string containing the XNET IP Stacks information.
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.
Frees the memory returned from nxIpStackGetAllStacksInfoStr. Always call this function when you are finished with the stacks information to avoid memory leaks.
void nxIpStackFreeAllStacksInfoStr( char* info);
Info: The pointer to the string returned from nxIpStackGetAllStacksInfoStr.
Waits for interface(s) in the IP Stack to be ready for communication.
nxStatus_t nxIpStackWaitForInterface ( nxIpStackRef_t stackRef, const char * localInterface, i32 timeoutMs);
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.
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 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.