Returns the top level group of a nested group element.

    GSErrCode ACAPI_Goodies (
        APIAny_GetMainGroupGuidID,
        const API_Guid*     groupGuid,
        API_Guid*           mainGroupGuid
    );

 

Parameters

groupGuid

[in] The guid of a group element.

mainGroupGuid

[out] The guid of the root group in the group hierarchy which contains the tested group.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

The groupGuid or the mainGroupGuid parameter is nullptr

APIERR_BADID

The passed groupGuid does not refer to an existing group element

For other common API errors see the API Errors document.

 

Remarks

This function is used to obtain the top level group of a nested group element. If the passed group is not part of another group, the function returns the passed group guid as main group guid.

 

Example

bool    GetMainGroupOfAnElement (const API_Element& element, API_Element* mainGroup)
{
    bool grouped = false;
    API_Guid mainGroupGuid = APINULLGuid;
    ACAPI_Goodies (APIAny_GetMainGroupGuidID, const_cast<API_Guid*> (&element.header.groupGuid), &mainGroupGuid);
    if (mainGroupGuid != APINULLGuid) {
        grouped = true;
        char msgStr[128];
        sprintf (msgStr, "Main Group Guid: %s", static_cast<const char *> (APIGuid2GSGuid (mainGroupGuid).ToUniString ().ToCStr ()));
        ACAPI_WriteReport (msgStr, false);

        if (mainGroup != nullptr) {
            BNZeroMemory (mainGroup, sizeof (API_Element));
            mainGroup->header.guid = mainGroupGuid;
            ACAPI_Element_Get (mainGroup);
        }
    }
    return grouped;
}

 

Requirements

Version: API 12 or later

Header: APIdefs_Goodies.h

 

See Also

ACAPI_Goodies, API Functions