A handle stores the unique identifier of an element within the scope of a single database. The database associates a handle with an element and stores the handle together with the element. When a database is saved into the file, handles are also saved with the elements, and they persist from one run-time session to another. Programmatically, a handle is a 64-bit integer value that is initialized by a database when a new element is added.
The OdDbHandle class implements a handle and represents the interface for getting and modifying an identification value. The OdDbHandle class does not inherit the standard database functionality; it is a number used for associating elements of a database. This class declares the OdUInt64 member that stores the identification value, methods for getting the value, and operators for modifying or comparing a handle. This class works with a handle either as an integer value or string value, and represents it in hexadecimal format.
Handles in ODA BimRv SDK start from 0. A positive or '0' handle means that the element is stored in the database. If a handle has the '-1' value, the element has no handle. A negative handle is a built-in element that is not stored in the database. ODA BimRv SDK stores handle values in the OdInt32 format; while working with elements and handles the value should be converted to OdUInt64 format.
Creating a Handle
To create a handle, use its constructor. The OdDbHandle class has an overloaded constructor that creates an instance using an integer value, ASCII string, wide-character string, 64-bit integer value, or other handle as an argument. A constructor without arguments initializes the handle with zero. For example:
OdBmCommandContextPtr pDbCmdCtx(pCmdCtx);
OdBmDatabasePtr pDb = pDbCmdCtx->database();
OdSmartPtr<OdBmUserIO> pIO = pDbCmdCtx->userIO();
// default value
OdDbHandle h1;
OdString message;
message.format(L"\nH1 = %s", h1.ascii().c_str());
pIO->putString(message); // H1 = 0
// an integer value
OdDbHandle h2(0x1F4A);
message.format(L"\nH2 = %s", h2.ascii().c_str());
pIO->putString(message); // H2 = 1f4a
// ascii-character string value
OdDbHandle h3("2CB5E3");
message.format(L"\nH3 = %s", h3.ascii().c_str());
pIO->putString(message); // H3 = 2cb5e3
// wide-character string value
OdDbHandle h4(OD_T("3C57B21E"));
message.format(L"\nH4 = %s", h4.ascii().c_str());
pIO->putString(message); // H4 = 3c57b21e
// 64-bit integer value
OdUInt64 vInt64 = 456123;
OdDbHandle h5(vInt64);
message.format(L"\nH5 = %s", h5.ascii().c_str());
pIO->putString(message); // H5 = 6f5bb
// OdString value
OdString sValue = L"42ED18AC";
OdDbHandle h6(sValue);
message.format(L"\nH6 = %s", h6.ascii().c_str());
pIO->putString(message); // H6 = 42ed18ac
// handle value
OdDbHandle hh(h4);
message.format(L"\nH = %s", hh.ascii().c_str());
pIO->putString(message); // H = 3c57b21e
Getting a Handle
To get the handle of an existing ID, use the handle() method of the OdBmObjectId object; it does not have arguments and returns the handle associated with this object. For example:
OdBmElementPtr elem = OdBmElement::createObject();
OdBmObjectId pObjId = elem->objectId();
//OdDbHandle hSelf = pObjId.getHandle();
message.format(L"\nHandle = %llx", pObjId);
pIO->putString(message);
Getting a Handle Value
To get a handle as a string value, use the ascii() method which returns the string of hexadecimal digits as a value of the OdString type. For example:
message.format(L"\nH = %s", hh.ascii().c_str());
pIO->putString(message);
To get a handle as a null-terminated string, use the getInfoAsciiBuffer() method which requires a pointer to an array of characters at least 17 bytes long and fills this array using hexadecimal digits obtained by dividing a 64-bit integer value by half-bytes. For example:
OdChar buffer[17];
hh.getIntoAsciiBuffer(buffer);
message.format(L"\n\"%s\"", buffer);
pIO->putString(message); // "3C57B21E"
To get a handle as an array of bytes, use the bytes() method which requires a pointer to an array containing eight values of the OdUInt8 type and fills this array using 8-bit integer values obtained by dividing a 64-bit integer value by 8 bytes. For example:
OdUInt8 chunk[8];
hh.bytes(chunk);
message.format(L"\nArray: ");
pIO->putString(message);
for (int i = 7; i >= 0; i--)
{
message.format(L"%x,", chunk[i]);
pIO->putString(message); // 0,0,0,0,3c,57,b2,1e,
}
To check whether a handle has an identifier, use the isNull() method which returns 'true' when the 64-bit integer value equals '-1' or returns 'false' when the handle is set to an identifier. A '-1' value denotes NULL for a handle. For example:
h1 = -1;
// H1 is null
message.format(L"\nH1 %s", (h1.isNull()) ? L"is null" : L"is not null");
pIO->putString(message);
// H2 is not null
message.format(L"\nH2 %s", (h2.isNull()) ? L"is null" : L"is not null");
pIO->putString(message);
Setting a Handle Value
To set a value to a handle, use the assignment operator that modifies an instance using an integer, 64-bit integer, ASCII string, wide-character string, or handle values. For example:
// an integer value
h2 = 0x2A3B4C;
message.format(L"\nH2 = %s", h2.ascii().c_str());
pIO->putString(message); // H2 = 2a3b4c
// ascii-character string value
h3 = "1AD2E3";
message.format(L"\nH3 = %s", h3.ascii().c_str());
pIO->putString(message); // H3 = 1ad2e3
// wide-character string value
h4 = OD_T("3C57B2");
message.format(L"\nH4 = %s", h4.ascii().c_str());
pIO->putString(message); // H4 = 3c57b2
// 64-bit integer value
h5 = vInt64;
message.format(L"\nH5 = %s", h5.ascii().c_str());
pIO->putString(message); // H5 = 6f5bb
// handle value
h6 = h4;
message.format(L"\nH6 = %s", h6.ascii().c_str());
pIO->putString(message); // H6 = 3c57b2
To modify a handle, use the addition operator which adds a 64-bit integer value to the current value of a handle. For example:
hh = 0x1F;
hh += 0x0E;
message.format(L"\nH = %s", hh.ascii().c_str());
pIO->putString(message); // H = 2d
// or
hh = 0xA3B6 + 0x1E2C;
message.format(L"\nH = %s", hh.ascii().c_str());
pIO->putString(message); // H = c1e2
Comparing and Forcing a Handle
To compare handles, use the comparison operators that compare the handles as 64-bit integer values and have an implementation for pairs: (handle ? handle) and (handle ? OdUInt64). For example:
h1 = 0; h2 = 5; h3 = 8; h4 = 5;
message.format(L"\n(h2 < h3) = %d, (h2 > h3) = %d", (h2 < h3), (h2 > h3));
pIO->putString(message);
message.format(L"\n(h3 <= h2) = %d, (h3 >= h2) = %d", (h3 <= h2), (h3 >= h2));
pIO->putString(message);
message.format(L"\n(h2 <= h4) = %d, (h2 >= h4) = %d", (h2 <= h4), (h2 >= h4));
pIO->putString(message);
message.format(L"\n(h2 == h3) = %d, (h2 != h3) = %d", (h2 == h3), (h2 != h3));
pIO->putString(message);
message.format(L"\n(h2 == h4) = %d, (h2 != h4) = %d", (h2 == h4), (h2 != h4));
pIO->putString(message);
// Result is following:
// (h2 < h3) = 1, (h2 > h3) = 0
// (h3 <= h2) = 0, (h3 >= h2) = 1
// (h2 <= h4) = 1, (h2 >= h4) = 1
// (h2 == h3) = 0, (h2 != h3) = 1
// (h2 == h4) = 1, (h2 != h4) = 0
A handle has an operator that casts it to a 64-bit integer value. For example:
hh = L"1D3F2C4B";
vInt64 = hh;
message.format(L"\nH = %llx", vInt64);
pIO->putString(message); // H = 1D3F2C4B
vInt64 = h1;
message.format(L"\nH = %llx", vInt64);
pIO->putString(message); // H = 0
The handle can be entered as a 64-bit integer value which can be assigned to an existing handle or can be passed as an argument of a function. For example:
vInt64 = pIO->getInt("Enter 64-bit handle");
OdDbHandle handle = vInt64;
OdBmElementPtr pElementPtr = pDb->getObjectId(vInt64).safeOpenObject();
Note: You can cast a 64-bit integer value to a handle, or you can cast a handle to a 64-bit integer value.