Nerve Gear data interface. More...

#include <NERvGear/interface/IData.h>

Inheritance diagram for NERvGear::IData:

Detailed Description

Nerve Gear data interface.

Note: Any index parameters for member functions are zero-based.

See also: NERvGear::IDataSource

Define ID:

const NERvGear::UID NERvGear::ID_IData; // 00000001-0000-0000-0000-004944617461

Public Member Functions
virtual long __stdcall	GetId (UID *id)=0
	Retrieves the UID of this data object. More...

virtual size_t __stdcall	GetName (size_t len, wchar_t *name)=0
	Retrieves the display name for this data. More...

virtual size_t __stdcall	GetDescrip (size_t len, wchar_t *descrip)=0
	Retrieves the description for this data. More...

virtual long __stdcall	QuerySource (IDataSource **source)=0
	Retrieves the source providing this data. More...

virtual unsigned __stdcall	GetValueCount ()=0
	Retrieves the number of values providing by this data.

virtual size_t __stdcall	GetValue (unsigned index, size_t nbyte, void *buf)=0
	Retrieves an current value of this data. More...

virtual size_t __stdcall	GetMaximum (unsigned index, size_t nbyte, void *buf)=0
	Retrieves an maximum value of this data. More...

virtual size_t __stdcall	GetMinimum (unsigned index, size_t nbyte, void *buf)=0
	Retrieves an minimum value of this data. More...

virtual unsigned __stdcall	GetValueIndex (int id)=0
	Retrieves the index of a data value. More...

virtual int __stdcall	GetValueId (unsigned index)=0
	Retrieves the ID of a data value. More...

virtual DATA::TYPE __stdcall	GetValueType (unsigned index)=0
	Retrieves the data type of a data value. More...

virtual size_t __stdcall	GetValueUnit (unsigned index, size_t len, wchar_t *unit)=0
	Retrieves the current unit of a data value. More...

virtual size_t __stdcall	GetValueName (unsigned index, size_t len, wchar_t *name)=0
	Retrieves the display name for a data value. More...

virtual size_t __stdcall	GetValueDescrip (unsigned index, size_t len, wchar_t *descrip)=0
	Retrieves the display name for a data value. More...

virtual unsigned __stdcall	GetUpdateInterval (unsigned index)=0
	Retrieves the recommended update interval for a data value. More...

virtual long __stdcall	Update (unsigned index=-1, const wchar_t *param=0)=0
	Update specified data values. More...

virtual long __stdcall	Invoke (unsigned index, const wchar_t param=0, UI::IWindow window=0)=0
	Reserved function. More...

virtual size_t __stdcall	Config (unsigned index, DATA::CONFIG type, UI::IWindow window, size_t len, wchar_t param)=0
	Retrieves the configuration string for specified data value. More...

virtual long __stdcall	SetValueUnit (unsigned index, const wchar_t *unit)=0
	Specifies the unit for a data unit. More...

virtual size_t __stdcall	EnumValueUnit (unsigned index, size_t len, wchar_t *units)=0
	Enumerates all units supported by a data value. More...

virtual long __stdcall	SetEventListener (IEventHandler *listener)=0
	Sets an event listener receiving update events for this data object. More...

Public Member Functions inherited from NERvGear::IUnknown
virtual long __stdcall	QueryInterface (const UID &interfaceID, void **ppvObject)=0

virtual unsigned long __stdcall	AddRef ()=0

virtual unsigned long __stdcall	Release ()=0

Member Function Documentation

virtual size_t __stdcall NERvGear::IData::Config	(	unsigned	index,
		DATA::CONFIG	type,
		UI::IWindow *	window,
		size_t	len,
		wchar_t *	param
	)

pure virtual

Retrieves the configuration string for specified data value.

The returned string could be used as the parameter for Update() or Invoke(), etc.

Parameters

[in]	index	A zero based number represents the value to configure.
[in]	type	Configuration type, one of the NERvGear::DATA::CONFIG enumeration values.
[in]	window	Reserved, must be NULL.
[in]	len	The size of param buffer, in characters. If param is NULL, this parameter must be 0.
[out]	param	A pointer to a buffer that receives the null terminated string for the parameter, could be NULL.

Remarks: See GetName() for more details about parameters and return values.

virtual size_t __stdcall NERvGear::IData::EnumValueUnit	(	unsigned	index,
		size_t	len,
		wchar_t *	units
	)

pure virtual

Enumerates all units supported by a data value.

Parameters

[in]	index	A zero based number represents the value to enumerate.
[in]	len	The buffer size of units, in characters. If units is NULL, this parameter must be 0.
[out]	units	A pointer to the buffer receiving a double-null-terminated string, could be NULL.

Returns: Returns the size copied into the string buffer, in characters.
If units is not NULL, the return value is the length of the string that is copied to the buffer, in characters, not including the terminating null characters.
If units is NULL and len is 0, the return value is the buffer size required to store the string, in characters, including the terminating null characters.
If the data value does not have any units, the return value is 0.

See also: NERvCopyStringDoubleNull()

virtual size_t __stdcall NERvGear::IData::GetDescrip	(	size_t	len,
		wchar_t *	descrip
	)

pure virtual

Retrieves the description for this data.

Remarks: See GetName() for more details about parameters and return values.

virtual long __stdcall NERvGear::IData::GetId ( UID * id )

pure virtual

Retrieves the UID of this data object.

Parameters

[out] id Pointer to a UID, must not be NULL.

Return values

S_OK	Success.
E_INVALIDARG	Fail. The id is NULL.
E_FAIL	Failed with unknown error.

Note: An ID of a data is unique for one data and must be different from any other data.

See also: IDataSource::FindData()

virtual size_t __stdcall NERvGear::IData::GetMaximum	(	unsigned	index,
		size_t	nbyte,
		void *	buf
	)

pure virtual

Retrieves an maximum value of this data.

Remarks: See GetValue() for more details about parameters and return values.

virtual size_t __stdcall NERvGear::IData::GetMinimum	(	unsigned	index,
		size_t	nbyte,
		void *	buf
	)

pure virtual

Retrieves an minimum value of this data.

Remarks: See GetValue() for more details about parameters and return values.

virtual size_t __stdcall NERvGear::IData::GetName	(	size_t	len,
		wchar_t *	name
	)

pure virtual

Retrieves the display name for this data.

Parameters

[in]	len	The size of name buffer, in characters. If name is NULL, this parameter must be 0.
[out]	name	A pointer to a buffer that receives the null terminated string for the display name, could be NULL.

Returns: Returns the size copied into the name buffer, in characters.
If name is not NULL, the return value is the length of the string that is copied to the buffer, in characters, not including the terminating null character.
If name buffer is too small to hold the name, the string is truncated to len characters including the terminating null character, and the return value is len.
If name is NULL and len is 0, the return value is the length of the string buffer required, in characters, including the terminating null character.
If the function fails, the return value is 0.

See also: NERvCopyString()

virtual unsigned __stdcall NERvGear::IData::GetUpdateInterval ( unsigned index )

pure virtual

Retrieves the recommended update interval for a data value.

Returns: Returns a recommended update interval, in millisecond.
If specified value supports auto or asynchronous update, the return value is 0. See SetEventListener() for more information.
If index is invalid or specified value does not exists, the return value is NVG_ANY(-1).

virtual size_t __stdcall NERvGear::IData::GetValue	(	unsigned	index,
		size_t	nbyte,
		void *	buf
	)

pure virtual

Retrieves an current value of this data.

Parameters

[in]	index	A zero based number represents the value to get.
[in]	nbyte	The buffer size of buf, in bytes. If buf is NULL, this parameter must be 0.
[out]	buf	A pointer to the buffer receiving a value, could be NULL.

Returns: Returns the size copied into the buffer, in bytes.
If buf is NULL and nbyte is 0, the return value is the buffer size required to store the value, in bytes.
If the data does not have specified value, the return value is 0.

Remarks: You should Update() before any calls to GetValue(), GetMaximum(), GetMinimum() to confirm values are up to date.

virtual size_t __stdcall NERvGear::IData::GetValueDescrip	(	unsigned	index,
		size_t	len,
		wchar_t *	descrip
	)

pure virtual

Retrieves the display name for a data value.

Remarks: See GetName() for more details about parameters and return values.

virtual int __stdcall NERvGear::IData::GetValueId ( unsigned index )

pure virtual

Retrieves the ID of a data value.

Returns: Returns a number locally represent a data value.

Return values

NVG_ANY Fail. The index is invalid.

Remarks: Call GetValueIndex() to retrieve the index of a data value with an ID.

Note: The ID returned by this function should identify a data value locally in a data space. Once an ID is bond to a value and published, the ID of one value should not be changed, while the index of a value could be changed if necessary in the future.

virtual unsigned __stdcall NERvGear::IData::GetValueIndex ( int id )

pure virtual

Retrieves the index of a data value.

Parameters

[in] id A number represent a data value in public.

Returns: Returns a zero based number privately represent a data value.

Return values

NVG_ANY Fail. The id is invalid.

Remarks: Call GetValueId() to retrieve the id of a data value.

virtual size_t __stdcall NERvGear::IData::GetValueName	(	unsigned	index,
		size_t	len,
		wchar_t *	name
	)

pure virtual

Retrieves the display name for a data value.

Remarks: See GetName() for more details about parameters and return values.

virtual DATA::TYPE __stdcall NERvGear::IData::GetValueType ( unsigned index )

pure virtual

Retrieves the data type of a data value.

Returns: Returns a data type which may be one of the enumeration values of NERvGear::DATA::TYPE.

Note: The type of the value could be changed after a call on Update(), so you should check value type every time you update a value if you're not sure.

virtual size_t __stdcall NERvGear::IData::GetValueUnit	(	unsigned	index,
		size_t	len,
		wchar_t *	unit
	)

pure virtual

Retrieves the current unit of a data value.

Remarks: See GetName() for more details about parameters and return values.

virtual long __stdcall NERvGear::IData::Invoke	(	unsigned	index,
		const wchar_t *	param = `0`,
		UI::IWindow *	window = `0`
	)

pure virtual

Reserved function.

Return values

E_NOTIMPL.

virtual long __stdcall NERvGear::IData::QuerySource ( IDataSource ** source )

pure virtual

Retrieves the source providing this data.

Parameters

[out] source A pointer to a buffer receiving the IDataSource pointer.

Return values

S_OK	Success.
E_INVALIDARG	Fail. The source is NULL.
E_FAIL	Failed with unknown error.

Note: The queried source must be the same object creating this data.

virtual long __stdcall NERvGear::IData::SetEventListener ( IEventHandler * listener )

pure virtual

Sets an event listener receiving update events for this data object.

If the data object supports auto or asynchronous update, the event handler will receive EVT::DATAUPDATE when a value is updated.

Parameters

[in] listener A pointer to the event handler that receives update events.

Return values

S_OK	Success.
E_INVALIDARG	Fail. The listener is NULL.
E_NOTIMPL	Fail, It's not implemented by this data object.
E_FAIL	Failed with unknown error.

Remarks

Difference between auto and asynchronous update:

Auto Update: The Update() call returns S_OK, EVT::DATAUPDATE will be sent to event handler continuous at the right time when a value is changed.
Asynchronous Update: The Update() call returns E_PENDING, EVT::DATAUPDATE will be sent one time when a value is updated

virtual long __stdcall NERvGear::IData::SetValueUnit	(	unsigned	index,
		const wchar_t *	unit
	)

pure virtual

Specifies the unit for a data unit.

Parameters

[in]	index	A zero based number represents the value to set unit.
[in]	unit	A pointer to the null terminated string returned by EnumValueUnit().

Return values

S_OK	Success.
E_INVALIDARG	Fail. The index is invalid or value does not exists, or unit is NULL or invalid.
E_FAIL	Fail. Specified value does not have unit, or failed to switch to specified unit.

virtual long __stdcall NERvGear::IData::Update	(	unsigned	index = `-1`,
		const wchar_t *	param = `0`
	)

pure virtual

Update specified data values.

Parameters

[in]	index	A zero based number represents the value to update, NVG_ANY means updating all values.
[in]	param	A pointer to the null terminated string as update parameter.

Return values

S_OK	Success.
E_PENDING	If event listener is set, the event handler will receive an EVT::DATAUPDATE event when value is updated. If event listener is not set, the values will be updated at undefined time.
E_INVALIDARG	Fail. The index is invalid or value does not exists.
E_FAIL	Failed with unknown error.

Note: This function must be called successfully at least once even if auto update is supported by this data.

Detailed Description

Public Member Functions

Member Function Documentation