User supplied callback procedure for handling element reservation changes.

    typedef GSErrCode  APIReservationChangeHandlerProc (
        const GS::HashTable<API_Guid, short>&   reserved,
        const GS::HashSet<API_Guid>&            released,
        const GS::HashSet<API_Guid>&            deleted



[in] List of elements recently reserved. The hash key in the hash table is the element guid, the paired value is the Teamwork owner identifier of the member who reserved the element.
[in] List of elements recently released.
[in] List of elements deleted during the recent Teamwork operations. Element deletions are reported when the member who deleted the elements sends the changes to the BIM Server.


Return Values

The function has completed with success.

For other common API errors see the API Errors document.



This callback function should be implemented and set with ACAPI_Notify_CatchElementReservationChange in order to receive notifications of element reservation changes.

You can retrieve information of the members with the APIEnv_ProjectSharingID environment function. Note that the handler receives reservation changes effected by the current team member as well.

In the reservation change handler try to avoid calling functions that would modify the database.



// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
GSErrCode __ACENV_CALL  ElementReservationChangeHandler (const GS::HashTable<API_Guid, short>&  reserved,
                                                         const GS::HashSet<API_Guid>&           /*released*/,
                                                         const GS::HashSet<API_Guid>&           /*deleted*/)
    GS::HashTable<API_ElemTypeID,Int32> reservedStat;

    for (GS::HashTable<API_Guid, short>::ConstPairIterator it = reserved.EnumeratePairs (); it != nullptr; ++it) {
        API_Elem_Head elemHead;
        BNZeroMemory (&elemHead, sizeof (API_Elem_Head));
        elemHead.guid = *(it->key);
        if (ACAPI_Element_GetHeader (&elemHead) == NoError)
            ++(reservedStat.Retrieve (elemHead.typeID, 0));     // counting elements of the same type

    if (!reservedStat.IsEmpty ()) {                             // print statistics of reserved elements
        GS::UniString reportString ("=  Recently reserved elements: ");
        for (GS::HashTable<API_ElemTypeID,Int32>::PairIterator it = reservedStat.EnumeratePairs (); it != nullptr; ++it) {
            GS::UniString elemTypeName;
            ACAPI_Goodies (APIAny_GetElemTypeNameID, (void*) *(it->key), &elemTypeName);
            GS::UniString elemCountStr = GS::UniString::Printf ("  %T:%d", elemTypeName.ToPrintf (), *(it->value));
            reportString.Append (elemCountStr);
        ACAPI_WriteReport (reportString.ToCStr ().Get (), false);

    return NoError;

// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
void    CatchElementReservationChanges (bool enableNotifications)
    if (enableNotifications)
        ACAPI_Notify_CatchElementReservationChange (ElementReservationChangeHandler);
        ACAPI_Notify_CatchElementReservationChange (nullptr);



Version: API 15 or later
Header: APIdefs_Callback.h


See Also

Teamwork Control
Notification Manager
API Functions