DS_Open
- Updated2023-02-21
- 6 minute(s) read
HRESULT DS_Open (const char *URL, DSEnum_AccessModes accessMode, DSCallbackPtr eventFunction, void *callbackData, DSHandle *DSHandle);
Purpose
Creates a DataSocket object and connects it to a data source. Call DS_DiscardObjHandle to free the DataSocket object's resources when you finish using it. It is recommended that you use DS_OpenEx instead of this function.
Each DataSocket object is connected to a single DataSocket data source. Use a URL to specify the location and format of the DataSocket data source. For each DataSocket object that you connect to a DataSocket data source, specify whether the connection is a read connection or a write connection. If you specify a read connection, you can use the DataSocket object to get data from the data source. If you specify a write connection, you can use the DataSocket object to send data to the data source.
Each DataSocket object stores a single data value and a set of attributes. Each attribute of a DataSocket object is also a DataSocket object.
When you configure a DataSocket object for writing, you can set the data value and the attributes of the DataSocket object. The DataSocket object transfers the data value and the attributes to the DataSocket data source. When you configure a DataSocket object for reading, it obtains the data value and the values of the attributes from the DataSocket data source. You get the data value and attributes directly from the DataSocket object.
 |
Note This function returns before the connection is completed. Wait until the connection status is set to connected before performing operations with the DataSocket handle returned by this function. If you specify a callback for a connection, your callback is called when the status of the connection changes. You also can check the status using the DS_GetStatus function. |
|
Note If you are interested in getting all the incoming data items and not just the latest data item, then you should initialize your thread to Apartment Threading Model by calling the CA_InitActiveXThreadStyleForCurrentThread ActiveX library function before calling this function. This prevents the current data item from getting over-written when the DataSocket object is making a call to your event function. |
|
Note The thread that calls this function should process messages by calling RunUserInterface, GetUserEvent, or ProcessSystemEvents as the DataSocket library posts messages to this thread. |
Parameters
| Input | ||
| Name | Type | Description |
| URL | const char * | The URL of the data source for the DataSocket object's connection. The URL you pass can resolve to different types of data sources. A URL consists of a scheme and a data source path. The scheme specifies the type of data. The DataSocket library supports the following URL schemes: http—hypertext transfer protocol ftp—file transfer protocol file—local files dstp—DataSocket transfer protocol opc—OPC (OLE for Process control) servers logos—an internal National Instruments technology for transmitting data between the network and your local computer fieldpoint—a protocol that uses the National Instrument logos protocol to send and receive live data to and from a National Instruments Fieldpoint module The data source path specifies the exact location of the data. The format of the data source path depends on the URL scheme. URL examples http://www.natinst.com/cworks/datasocket/chirp.dsd ftp://ftp.natinst.com/support/compworks/datasocket/chirp.wav dstp://localhost/wave dstp://weather.natinst.com/weather/current file://datafiles/newwave.txt opc://machine/National Instruments.OPCDemo/SINE:0.0..8.0:2.0 logos://computer_name/process/data_item_name fieldpoint://computer_name/process/data_item_name |
| accessMode | DSEnum_AccessModes | The access mode constant for the DataSocket object's connection. The access mode determines whether the DataSocket object can read from the DataSocket data source or write to the DataSocket data source. The access mode also determines when data is transferred from the data source to the DataSocket object or from the DataSocket object to the data source. You can specify the following constants. DSConst_Read—Configures the DataSocket object for manual updating. The DataSocket object gets data from the DataSocket data source at the time that the connection is established and when you call DS_Update. DSConst_ReadAutoUpdate—Configures the DataSocket object for automatic updating. The DataSocket object gets data from the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. This mode is valid only for DSTP and Logos and OPC data sources. DSConst_Write—Configures the DataSocket object for manual updating. The DataSocket object transfers data to the DataSocket data source at the time that the connection is established and when you call DS_Update. DSConst_WriteAutoUpdate—Configures the DataSocket object for automatic updating. The DataSocket object transfers data to the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. DSConst_ReadWriteAutoUpdate—Configures the DataSocket object for automatic updating. The DataSocket object transfers data to the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. The DataSocket object gets data from the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. This mode is useful when the DataSocket data source has multiple writers. DSConst_ReadBuffered—Configures the DataSocket object for manual updating with buffering. The DataSocket object gets the next data in the buffer from the DataSocket data source at the time that the connection is established and when you call DS_Update. DSConst_ReadBufferedAutoUpdate—Configures the DataSocket object for automatic updating with buffering. The DataSocket object gets the data from the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. DSConst_ReadWriteBufferedAutoUpdate—Configures the DataSocket object for automatic updating with buffering. The DataSocket object transfers data to the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. The DataSocket object gets data from the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. This mode is useful when the DataSocket data source has multiple writers. |
| eventFunction | DSCallbackPtr | The callback function for the DataSocket object. The DataSocket object calls this callback when one or more of the following items have changed: the DataSocket object's data value, any of the DataSocket object's attributes, or the DataSocket object's status. Pass NULL for this parameter if you do not want to receive events. If you pass NULL for this parameter on a read connection, then you may lose data, as you will not be notified about data update events. This is the case even if the access mode is DSConst_ReadBufferedAutoUpdate or DSConst_ReadBuffered, and so, it is highly recommended that you pass a valid callback function for this parameter in read mode. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (DSHandle dsHandle, int event, void *callbackData); Upon entry to the callback, the dsHandle parameter contains the handle to the DataSocket object that is generating the event. The event parameter specifies the event that occurred. The callbackData parameter contains the value you passed in the callbackData parameter of this function.The following are possible values for the event parameter: DS_EVENT_DATAUPDATED—Occurs when the DataSocket object's data value or one of its attributes has changed. DS_EVENT_STATUSUPDATED—Occurs when the DataSocket object's status has changed. |
| callbackData | void * | The value that you want the DataSocket object to pass to your callback as the callbackData parameter. Do not pass the address of a local variable or any other variable that might not be valid when the function is executed. |
| Output | ||
| Name | Type | Description |
| DSHandle | DSHandle | Returns a handle that you use to identify the DataSocket object in subsequent function calls. The handle is never 0. Call DS_DiscardObjHandle to free the DataSocket object's resources when you are done using it. |
Return Value
| Name | Type | Description |
| status | HRESULT | The value that indicates whether an error occurred. A negative error code indicates function failure. Error codes are defined in CVIversion\toolslib\datasock\dataskt.h and <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h. Other error codes in winerror.h are generated by ActiveX Servers and are passed on to you by the DataSocket Library. |
Additional Information
Library: DataSocket Library
Include file: datasock\dataskt.h
LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later