int CNVCreateBufferedSubscriber (const char *networkVariablePathname, CNVStatusCallback statusCallback, void *callbackData, int clientBufferMaxItems, int waitTime, intptr_t reserved, CNVBufferedSubscriber *bufferedSubscriber);


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 Note  To avoid deadlocks, do not call this function in a network variable callback function.


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:

  • \\localhost\my_process\my_folder1\my_folder2\my_variable
  • \\test_machine\my_process\my_sub_process\my_variable
  • \\\my_process\my_variable
  • \\\my_process\my_variable
  • \\localhost\System\DAQmx\Server Polling Rate
  • \\localhost\system\my_variable

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.

Note Note  National Instruments recommends that you use only alphanumeric characters in process, folder, and variable names. If the name contains single quotation mark ('), backslash (\), period (.), newline (\n), or carriage return (\r) characters, you must escape these characters by enclosing the name in single quotation marks. If the contains single quotation mark characters, you also must precede that character with another single quotation mark.

For example, to specify \\localhost\process'Name\variable.Name as a URL, enter the following:

  • 'process''Name' as the process name
  • 'variable.Name' as the variable name

The resulting URL is \\localhost\\'process''Name'\'variable.Name'.

This rule does not apply to computer names.
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.

Note  Return from this function as soon as possible to avoid blocking other network variable events and operations. If needed, you can use PostDeferredCallToThread to process this event on a different thread. From within this callback function, you must also avoid calling the Network Variable Library to create or dispose connections and browsers, get or put buffered data, read or write data, get or set connection attributes, and browse for variables to prevent deadlocks.
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.
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


Refer to the following examples that use the CNVCreateBufferedSubscriber function:

  • networkvariable\Buffering\NVBuffering.cws

    Open example
  • networkvariable\Polling\NVPolling.cws

    Open example


Not Helpful