Tango Core Classes Reference  9.3.3
Tango::DeviceData Class Reference

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

◆ DeviceData()

Tango::DeviceData::DeviceData ( )

Create a DeviceData object.

Default constructor. The instance is empty

Member Function Documentation

◆ exceptions() [1/2]

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

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

◆ exceptions() [2/2]

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]flThe exception flag

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

◆ extract() [1/3]

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]strThe DevEncoded string
[out]dataThe DevEncoded data pointer
[out]lengthThe DevEncoded data length
Returns
Boolean set to false if the extraction failed
Exceptions
WrongDataif requested

◆ extract() [2/3]

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]vlThe long vector which will be inialized
[out]vsThe string vector to be initialized
Returns
Boolean set to false if the extraction failed
Exceptions
WrongDataif requested

◆ extract() [3/3]

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]vdThe double vector to be initialized
[out]vsThe string vector to be initialized
Returns
Boolean set to false if the extraction failed
Exceptions
WrongDataif requested

◆ get_type()

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

◆ insert() [1/3]

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]strThe string part of the DevEncoded instance
[in]bufferThe data part of the DevEncoded instance
Exceptions
WrongDataif requested

◆ insert() [2/3]

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]vlThe long vector to be inserted
[in]vsThe string vector to be inserted
Exceptions
WrongDataif requested

◆ insert() [3/3]

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]vdThe double vector to be inserted
[in]vsThe string vector to be inserted
Exceptions
WrongDataif requested

◆ is_empty()

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

◆ operator<<()

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<bool>
  • 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 :

  • DevVarBooleanArray *
  • 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 :

  • DevVarBooleanArray &
  • 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]datumThe data to be inserted
Exceptions
WrongDataif requested

◆ operator>>()

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<bool>
  • 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 DevVarBooleanArray *
  • 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]datumThe variable which will be initalized
Returns
Boolean set to false if the extraction failed
Exceptions
WrongDataif requested

◆ reset_exceptions()

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

Reset one exception flag.

Resets one exception flag

Parameters
[in]flThe exception flag

◆ set_exceptions()

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]flThe exception flag

◆ state()

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

◆ operator<<

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(“...”);
out = dev->command_inout(“MyCommand”);
cout << “Command returned: ” << out << endl;
Parameters
[in]strThe printing stream
[in]ddThe instance to be printed

The documentation for this class was generated from the following file:
Tango::DeviceData::DeviceData
DeviceData()
Create a DeviceData object.