Fundamental type for sending and receiving data from device commands. More...

#include "tango.h"

Inheritance diagram for Tango::DeviceData:

Public Member Functions
Constructors
	DeviceData ()
	Create a DeviceData object. More...

Inserters and Extractors
void	operator<< (bool datum)
	The insert operators. More...

void	insert (vector< DevLong > &vl, vector< string > &vs)
	Insert data into a DeviceData for the DevVarLongStringArray data type. More...

void	insert (vector< double > &vd, vector< string > &vs)
	Insert data into a DeviceData for the DevVarDoubleStringArray data type. More...

void	insert (const string &str, vector< unsigned char > &buffer)
	Insert data into a DeviceData for the DevEncoded data type. More...

bool	operator>> (bool &datum)
	The extract operators. More...

bool	extract (vector< DevLong > &vl, vector< string > &vs)
	Extract data from a DeviceData for the DevVarLongStringArray data type. More...

bool	extract (vector< double > &vd, vector< string > &vs)
	Extract data from a DeviceData for the DevVarDoubleStringArray data type. More...

bool	extract (const char &str, const unsigned char &data, unsigned int &length)
	Extract data from a DeviceData for the DevEncoded data type. More...

Exception and error related methods methods
void	exceptions (bitset< numFlags > fl)
	Set exception flag. More...

bitset< numFlags >	exceptions ()
	Get exception flag. More...

void	reset_exceptions (except_flags fl)
	Reset one exception flag. More...

void	set_exceptions (except_flags fl)
	Set one exception flag. More...

bitset< numFlags >	state ()
	Get instance extraction state. More...

miscellaneous methods
bool	is_empty ()
	Check if the DeviceData instance is empty. More...

int	get_type ()
	Get Tango data type of the included data. More...

Friends
ostream &	operator<< (ostream &str, DeviceData &dd)
	Print a DeviceData instance. More...

Detailed Description

Fundamental type for sending and receiving data from device commands.

This is the fundamental type for sending and receiving data from device commands. The values can be inserted and extracted using the operators << and >> respectively and insert() for mixed data types. A status flag indicates if there is data in the DbDatum object or not. An additional flag allows the user to activate exceptions.

Insertion by pointers takes full ownership of the pointed to memory. The insertion copy the data in the DeviceData object and delete the pointed to memory. Therefore, the memory is not more usable after the insertion.
When using extraction by pointers, the pointed to memory is inside the DeviceData object and its lifetime is the same than the DeviceData object lifetime.

Author: taurel

Revision: 1

Constructor & Destructor Documentation

Tango::DeviceData::DeviceData ( )

Create a DeviceData object.

Default constructor. The instance is empty

Member Function Documentation

void Tango::DeviceData::exceptions ( bitset< numFlags > fl )

inline

Set exception flag.

It's a method which allows the user to switch on/off exception throwing when trying to extract data from a DeviceData object. The following flags are supported :

isempty_flag - throw a Empty DeviceData exception (reason = API_EmptyDeviceData) if user tries to extract data from an empty DeviceData object. By default, this flag is set
wrongtype_flag - throw a WrongData exception (reason = API_IncompatibleArgumentType) if user tries to extract data with a type different than the type used for insertion. By default, this flag is not set

Parameters

[in] fl The exception flag

Referenced by Tango::GroupCmdReply::operator>>().

bitset<numFlags> Tango::DeviceData::exceptions ( )

inline

Get exception flag.

Returns the whole exception flags. The following is an example of how to use these exceptions related methods

DeviceData dd;
bitset<DeviceData::numFlags> bs = dd.exceptions();
cout << "bs = " << bs << endl;
da.set_exceptions(DeviceData::wrongtype_flag);
bs = dd.exceptions();
cout << "bs = " << bs << endl;

Returns: The exception flag

bool Tango::DeviceData::extract	(	vector< DevLong > &	vl,
		vector< string > &	vs
	)

Extract data from a DeviceData for the DevVarLongStringArray data type.

Extract data from a DeviceData for the DevVarLongStringArray data type

Parameters

[out]	vl	The long vector which will be inialized
[out]	vs	The string vector to be initialized

Returns: Boolean set to false if the extraction failed

Exceptions

WrongData if requested

bool Tango::DeviceData::extract	(	vector< double > &	vd,
		vector< string > &	vs
	)

Extract data from a DeviceData for the DevVarDoubleStringArray data type.

Extract data from a DeviceData for the DevVarDoubleStringArray data type

Parameters

[out]	vd	The double vector to be initialized
[out]	vs	The string vector to be initialized

Returns: Boolean set to false if the extraction failed

Exceptions

WrongData if requested

bool Tango::DeviceData::extract	(	const char *&	str,
		const unsigned char *&	data,
		unsigned int &	length
	)

Extract data from a DeviceData for the DevEncoded data type.

Extract command data when the command data type is DevEncoded Similar method with following signature also exist

extract(string &str,vector<unsigned char> &data);

Parameters

[out]	str	The DevEncoded string
[out]	data	The DevEncoded data pointer
[out]	length	The DevEncoded data length

Returns: Boolean set to false if the extraction failed

Exceptions

WrongData if requested

int Tango::DeviceData::get_type ( )

Get Tango data type of the included data.

This method returns the Tango data type of the data inside the DeviceData object

Returns: The data type

void Tango::DeviceData::insert	(	vector< DevLong > &	vl,
		vector< string > &	vs
	)

Insert data into a DeviceData for the DevVarLongStringArray data type.

Insert data into a DeviceData for the DevVarLongStringArray data type

Parameters

[in]	vl	The long vector to be inserted
[in]	vs	The string vector to be inserted

Exceptions

WrongData if requested

void Tango::DeviceData::insert	(	vector< double > &	vd,
		vector< string > &	vs
	)

Insert data into a DeviceData for the DevVarDoubleStringArray data type.

Insert data into a DeviceData for the DevVarDoubleStringArray data type

Parameters

[in]	vd	The double vector to be inserted
[in]	vs	The string vector to be inserted

Exceptions

WrongData if requested

void Tango::DeviceData::insert	(	const string &	str,
		vector< unsigned char > &	buffer
	)

Insert data into a DeviceData for the DevEncoded data type.

Insert data into a DeviceData for the DevEncoded data type
Similar methods with different parameters data type exist for inserting data for a DevEncoded data type

void insert(const char *str, DevVarCharArray *data);
void insert(const char *str, unsigned char *data,unsigned int length);

These three methods do not take ownership of the memory used for the data buffer.

Parameters

[in]	str	The string part of the DevEncoded instance
[in]	buffer	The data part of the DevEncoded instance

Exceptions

WrongData if requested

bool Tango::DeviceData::is_empty ( )

Check if the DeviceData instance is empty.

is_empty() is a boolean method which returns true or false depending on whether the DeviceData object contains data or not. It can be used to test whether the DeviceData has been initialized or not but you have first to disable exception throwing in case of empty object e.g.

string string_read;
DeviceData sl_read = my_device->command_inout(“ReadLine”);
sl_read.reset_exceptions(DeviceData::isempty_flag);
if (! sl_read.is_empty())
{
   sl_read >> string_read;
}
else
{
   cout << “ no data read from serial line !” << endl;
}

Returns: Boolean set to true is the instance is empty

void Tango::DeviceData::operator<< ( bool datum )

inline

The insert operators.

The insert operators are specified for the following C++ types :

bool
short
unsigned short
DevLong
DevULong
DevLong64
DevULong64
DevState
DevEncoded
float
double
string
char* (insert only)
const char *
vector<unsigned char>
vector<string>
vector<short>
vector<unsigned short>
vector<DevLong>
vector<DevULong>
vector<DevLong64>
vector<DevULong64>
vector<float>
vector<double>

Operators exist for inserting the native TANGO CORBA sequence types. These can be useful for programmers who want to use the TANGO api internally in their device servers and do not want to convert from CORBA to C++ types. Insert and extract operators exist for the following types :

DevVarUCharArray *
DevVarShortArray *
DevVarUShortArray *
DevVarLongArray *
DevVarULongArray *
DevVarLong64Array *
DevVarULong64Array *
DevVarFloatArray *
DevVarDoubleArray *
DevVarStringArray *
DevVarLongStringArray *
DevVarDoubleStringArray *

Insertion by pointers takes full ownership of the pointed to memory. The insertion copy the data in the DeviceData object and delete the pointed to memory. Therefore, the memory is not more usable after the insertion.

Operators also exist for inserting TANGO CORBA sequence type by reference. The insertion copy the data into the DeviceData object. Insert operator exist for the following types :

DevVarUCharArray &
DevVarShortArray &
DevVarUShortArray &
DevVarLongArray &
DevVarULongArray &
DevVarLong64Array&
DevVarULong64Array&
DevVarFloatArray &
DevVarDoubleArray &
DevVarStringArray &
DevVarLongStringArray&
DevVarDoubleStringArray&

Special care has been taken to avoid memory copy between the network layer and the user application. Nevertheless, C++ vector types are not the CORBA native type and one copy is unavoidable when using vectors. Using the native TANGO CORBA sequence types avoid any copy. When using these TANGO CORBA sequence types, insertion into the DeviceData object consumes the memory pointed to by the pointer. After the insertion, it is not necessary to delete the memory. It will be done by the destruction of the DeviceData object. For extraction, the pointer used for the extraction points into memory inside the DeviceData object and you should not delete it Here is an example of creating, inserting and extracting some data type from/into DeviceData object :

DeviceData my_short, my_long, my_string;
DeviceData my_float_vector, my_double_vector;
string a_string;
short a_short;
DevLong a_long;
vector<float> a_float_vector;
vector<double> a_double_vector;
my_short << 100; // insert a short
my_short >> a_short; // extract a short
my_long << 1000; // insert a long
my_long >> a_long; // extract a long
my_string << string(“estas lista a bailar el tango ?”); // insert a string
my_string >> a_string; // extract a string
my_float_vector << a_float_vector // insert a vector of floats
my_float_vector >> a_float_vector; // extract a vector of floats
my_double_vector << a_double_vector; // insert a vector of doubles
my_double_vector >> a_double_vector; // extract a vector of doubles
//
// Example of memory management with TANGO sequence types without memory leaks
//
for (int i = 0;i < 10;i++)
{
   DeviceData din,dout;
   DevVarLongArray *in = new DevVarLongArray();
   in->length(2);
   (*in)[0] = 2;
   (*in)[1] = 4;
   din << in;
   try
   {
      dout = device->command_inout(“Cmd”,din);
   }
   catch(DevFailed &e)
   {
      ....
   }
   const DevVarLongArray *out;
   dout >> out;
   cout << “Received value = “ << (*out)[0];
}

Parameters

[in] datum The data to be inserted

Exceptions

WrongData if requested

bool Tango::DeviceData::operator>> ( bool & datum )

The extract operators.

The extract operators are specified for the following C++ types :

bool
short
unsigned short
DevLong
DevULong
DevLong64
DevULong64
float
double
string
char* (insert only)
const char *
DevEncoded
DevState
vector<unsigned char>
vector<string>
vector<short>
vector<unsigned short>
vector<DevLong>
vector<DevULong>
vector<DevLong64>
vector<DevULong64>
vector<float>
vector<double>

Operators exist for extracting the native TANGO CORBA sequence types. These can be useful for programmers who want to use the TANGO api internally in their device servers and do not want to convert from CORBA to C++ types. Insert and extract operators exist for the following types :

const DevVarUCharArray *
const DevVarShortArray *
const DevVarUShortArray *
const DevVarLongArray *
const DevVarULongArray *
const DevVarLong64Array *
const DevVarULong64Array *
const DevVarFloatArray *
const DevVarDoubleArray *
const DevVarStringArray *
const DevVarLongStringArray *
const DevVarDoubleStringArray *

Note that when using extraction by pointers, the pointed to memory is inside the DeviceData object and its lifetime is the same than the DeviceData object lifetime.

Special care has been taken to avoid memory copy between the network layer and the user application. Nevertheless, C++ vector types are not the CORBA native type and one copy is unavoidable when using vectors. Using the native TANGO CORBA sequence types avoid any copy. When using these TANGO CORBA sequence types, for extraction, the pointer used for the extraction points into memory inside the DeviceData object and you should not delete it See DeviceData::operator<< for inserters and extractors usage example

Parameters

[out] datum The variable which will be initalized

Returns: Boolean set to false if the extraction failed

Exceptions

WrongData if requested

void Tango::DeviceData::reset_exceptions ( except_flags fl )

inline

Reset one exception flag.

Resets one exception flag

Parameters

[in] fl The exception flag

void Tango::DeviceData::set_exceptions ( except_flags fl )

inline

Set one exception flag.

Sets one exception flag. See DeviceData::exceptions() for a usage example.

Parameters

[in] fl The exception flag

bitset<numFlags> Tango::DeviceData::state ( )

inline

Get instance extraction state.

Allow the user to find out what was the reason of extraction from DeviceData failure. This method has to be used when exceptions are disabled. Here is an example of how method state() could be used

DeviceData dd = ....
bitset<DeviceData::numFlags> bs;
da.exceptions(bs);
DevLong dl;
if ((da >> dl) == false)
{
   bitset<DeviceData::numFlags> bs_err = da.state();
   if (bs_err.test(DeviceData::isempty_flag) == true)
       .....
}

Returns: The error bit set.

Friends And Related Function Documentation

ostream& operator<<	(	ostream &	str,
		DeviceData &	dd
	)

friend

Print a DeviceData instance.

Is an utility function to easily print the contents of a DeviceData object. This function knows all types which could be inserted in a DeviceData object and print them accordingly. A special string is printed if the DeviceData object is empty

DeviceProxy *dev = new DeviceProxy(“...”);
DeviceData out;
out = dev->command_inout(“MyCommand”);
cout << “Command returned: ” << out << endl;

Parameters

[in]	str	The printing stream
[in]	dd	The instance to be printed

The documentation for this class was generated from the following file:

devapi.h

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation