CNVCreateAsyncReader
int CNVCreateAsyncReader (const char *networkVariablePathname, CNVDataCallback dataCallback, CNVStatusCallback statusCallback, void *callbackData, int waitTime, intptr_t reserved, CNVAsyncReader *asynchronousReader);
Purpose
Creates an asynchronous reader connection to the network variable that you specify with the networkVariablePathname parameter. You can asynchronously read new values of the network variable by calling CNVReadAsync. The dataCallback is called with the data that an asynchronous read operation returns.
 |
Note The throughput rate of data with reader and asynchronous reader connections is slower than with subscriber and buffered subscriber connections. If throughput rate is critical to your application, consider using a subscriber or buffered subscriber connection instead. |
|
Note To avoid deadlocks, do not call this function in a network variable callback function. |
Parameters
| Input | ||||
| Name | Type | Description | ||
| networkVariablePathname | const char * | Pathname of the network variable to connect. The format of the pathname is \\machineName\processName\folderNames\variableName, which is similar to the format of items on network shares and is not case-sensitive. The following list shows examples of pathnames:
You can explicitly create and configure your variables using the NI Distributed System Manager that ships with LabWindows/CVI or using the Configuration Functions in the Network Variable Library. You also can use previously created explicit variables. If you specify a new variable name in the system process, as shown in the last example, then the Network Variable Library creates a variable implicitly. Implicit variables can hold values of any type, always have the single-writer restriction, and do not support server-side buffering. The Network Variable Library automatically deletes an implicit variable when all of its clients disconnect, that is, when there are no outstanding connections to it. Carefully decide whether to use implicit or explicit variables depending on your application and deployment needs.
|
||
| dataCallback | CNVDataCallback | The function that the library calls when the network variable connection receives data. The system generates data when the value, quality, or timestamp of the variable changes. The library calls this function asynchronously in a worker thread. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (void * handle, CNVData data, void * callbackData); Upon entry to the callback, the handle parameter contains the handle of the connection that is generating the event. The data parameter contains the handle of the received network variable data. Call CNVDisposeData to dispose the handle when you are done using it. The callbackData parameter of the callback contains the value you provide in the callbackData parameter of this function.
|
||
| statusCallback | CNVStatusCallback | The function that the library calls when the connection status of a successfully created network variable changes. Connection status events occur when there is a significant network delay and NI-PSP attempts to reconnect. The library calls this function asynchronously in a worker thread. You can pass NULL if you do not want this notification. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (void * handle, CNVConnectionStatus status, int error, void * callbackData); Upon entry to the callback, the handle parameter contains the handle of the connection that is generating the event. The status parameter contains the status of the connection. The error parameter indicates any errors in the connection. The callbackData parameter of the callback contains the value you provide in the callbackData parameter of this function.
|
||
| callbackData | void * | The callback data that the library passes to the associated callback functions. | ||
| waitTime | int | Number of milliseconds the library waits for this operation to complete. Pass CNVWaitForever to wait indefinitely. | ||
| reserved | intptr_t | You must pass zero. This parameter is reserved for future use. | ||
| Output | ||||
| Name | Type | Description | ||
| asynchronousReader | CNVAsyncReader | Returns a handle that you can use to identify this network variable connection in subsequent function calls. Call CNVDispose to dispose the handle when you are done using it. | ||
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. One indicates that a next item was found, zero indicates that a next item was not found, and a negative number indicates that an error occurred. You can call CNVGetErrorDescription to obtain a string that describes the error. |
Additional Information
Library: Network Variable Library
Include file: cvinetv.h
LabWindows/CVI compatibility: LabWindows/CVI 8.1 and later