CNVCreateBufferedSubscriber
int CNVCreateBufferedSubscriber (const char *networkVariablePathname, CNVStatusCallback statusCallback, void *callbackData, int clientBufferMaxItems, int waitTime, intptr_t reserved, CNVBufferedSubscriber *bufferedSubscriber);
Purpose
Creates a client-buffered subscriber connection to the network variable that you specify with the networkVariablePathName parameter.
When the status of the established connection changes, the statusCallback function is called with the new status. Connection status changes occur when there is a significant network delay and NI-PSP attempts to reconnect.
When the value of the network variable changes, it is automatically sent to the client and buffered. You can get the buffered values of the network variable by calling CNVGetDataFromBuffer. When the subscription is successful, the buffer contains the current value of the variable; if the variable is uninitialized and does not have a value, the buffer contains data of type CNVEmpty.
 |
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.
|
||
| 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. | ||
| clientBufferMaxItems | int | Maximum number of items to hold in the client buffer. This value must be greater than one. Note that multiple connections to the same URL share resources within a program. So, in your program, if another connection to the same URL has specified a client buffer that is larger, then the larger value will apply. | ||
| 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 | ||
| bufferedSubscriber | CNVBufferedSubscriber | 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
Examples
Refer to the following examples that use the CNVCreateBufferedSubscriber function:
- networkvariable\Buffering\NVBuffering.cws
Open example - networkvariable\Polling\NVPolling.cws
Open example