The interface for working with extended data is implemented in the OdDbObject class, which is the base class for all objects of a database. As a result, all objects of any database inherit the extended data functionality and can attach data itself. The base interface declares the xData() method for getting the extended data, setXData() method for setting the extended data, and the xDataTransformBy() method for applying the three-dimensional transformation matrix to the extended data.

Extended data is associated with an external application, therefore operations for getting and setting require a name of the application that owns the data. Extended data consists of sequences of resbuf-instances. Each sequence is associated with an external application that must be registered in the predefined table of named records. The xData() method can obtain the extended data associated with the specified registered application or extended data for all applications. The setXData() method can attach the extended data for the specified registered application or replace all data. The xDataTransformBy() method modifies the extended data for the appointed group codes. In the following examples, the pObj variable stores a pointer to an object of a database.

Getting XData

To get the XData attached to an object, declare a variable of the OdResBufPtr type and use the xData() method which requires the registered application name as an optional argument of the OdString type and returns the typified smart pointer to the sequence of resbuf-instances which have the OdResBuf type. The argument is an empty string by default. The returned pointer stores the beginning of the sequence.

To get the whole XData attached to an object, use the xData() method without arguments. For example:

OdResBufPtr pXData = pObj->xData();

To get the XData associated with an external application, use the xData() method and pass to it the registered application name as an argument. The xData() method returns the sequence only for the specified application. For example:

OdResBufPtr pXData = pObj->xData(L"ODA");

To print the obtained sequence of resbuf-instances, declare a variable of the OdResBufPtr type, initialize this variable to the beginning of the sequence, and move the iterator to the next resbuf-instance using the next() method while this variable is not set to NULL. For example:

odPrintConsoleString(L"\nXData:\n");
OdResBufPtr pRb = pXData;
while(pRb != NULL)
{
  odPrintConsoleString(L"%s\n", AboutXDataGroupCode(pRb));
  pRb = pRb->next();
}

Note: A program should not move the smart pointer returned by the xData() method because it loses the beginning of the sequence.

Setting XData

To set the XData for an object, build the dynamically linked sequence of resbuf-instances, initialize each resbuf-instance in the sequence, and use the setXData() method which requires a pointer to the dynamically linked sequence of resbuf-instances and does not return a value. The first resbuf-instance in the sequence must have the group code kDxfRegAppName (1001) and must store the name of the registered application whose extended data must be replaced for the object. For example:

OdResBufPtr pXData;

pXData = OdRusBuf::newRb(OdResBuf::kDxfRegAppName, L"ODA");

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdAsciiString, L"ODA Data") );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kRtInt16, (OdInt16) 12356) );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdControlString, L"{") );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdXCoord, OdGePoint3d(3.2, 1.3, 6.5)) );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdScale, 1.5) );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdControlString, L"}") );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdLayerName, L"0") );

pXData->last()->setNext( OdResBuf::newRb(OdResBuf::kDxfXdReal, 32.54E4) );

pObject->setXData(pXData);

Note: If an application is not registered, the setXData() method generates the exception: "126 - Invalid RegApp".

Clearing XData

To clear the extended data for a registered application, specify the sequence that contains only one resbuf-instance with the kDxfRegAppName group code and application name. The setXData() method clears the data set for the specified application when the passed sequence is empty. For example:

OdResBufPtr pEmptyData = OdRusBuf::newRb(OdResBuf::kDxfRegAppName, L"ODA");

pObject->setXData(pEmptyData);

Transforming XData

To transform the XData of an object, create and initialize a three-dimensional transformation matrix and use the xDataTransformBy() method that requires a matrix as an instance of the OdGeMatrix3d type and does not return a value. This method applies the transformation matrix for the following group codes: kDxfXdWorldXCoord (1011), kDxfXdWorldYCoord (1021), kDxfXdWorldZCoord (1031), kDxfXdWorldXDisp (1012), kDxfXdWorldYDisp (1022), kDxfXdWorldZDisp (1032), kDxfXdWorldXDir (1013), kDxfXdWorldYDir (1023), kDxfXdWorldZDir (1033), kDxfXdDist (1041), kDxfXdScale (1042). Other group codes are permanent for the transformation operation. For example:

OdGeMatrix3d tMatrix;
tMatrix[0][0] = 9.5;  tMatrix[0][1] = 0;    tMatrix[0][2] = 0.5;  tMatrix[0][3] = -8.2;
tMatrix[1][0] = 0;    tMatrix[1][1] = 9.5;  tMatrix[1][2] = 0;    tMatrix[1][3] = -8.2;
tMatrix[2][0] = 0.5;  tMatrix[2][1] = 0;    tMatrix[2][2] = 9.5;  tMatrix[2][3] = -8.2;
tMatrix[3][0] = 0;    tMatrix[3][1] = 0;    tMatrix[3][2] = 0;    tMatrix[3][3] = 1;

pObject->xDataTransformBy(tMatrix);

Note: If extended data is empty for the registered application, the xDataTransformBy() method generates the exception: "67 - Invalid group code".

See Also

Working with Extended Data

Example of Working with Extended Data