API_​Favorite

A container for Favorite entry settings.

    typedef struct {
        GS::UniString                                            name;
        API_Element                                              element;
        GS::Optional<API_ElementMemo>                            memo;
        GS::Optional<API_Element>                                elementMarker;
        GS::Optional<API_ElementMemo>                            memoMarker;
        GS::Optional<GS::Array<API_Property>>                    properties;
        GS::Optional<GS::Array<GS::Pair<API_Guid, API_Guid>>>    classifications;
        GS::Optional<GS::Array<API_ElemCategoryValue>>           elemCategoryValues;
        GS::Optional<API_FavoriteFolderHierarchy>                folder;
    } API_Favorite;
    

 

Members

name
Unique name identifier of the Favorite.
element
The element settings of the Favorite.
memo
(Optional) The element memo settings of the Favorite.
elementMarker
(Optional) The marker element settings of the Favorite.
memoMarker
(Optional) The marker element’s memo settings of the Favorite.
properties
(Optional) The properties of the Favorite.
classifications
(Optional) The classification system and classification item pairs of the Favorite.
elemCategoryValues
(Optional) The element categories of the Favorite.
folder
(Optional) The folder of the Favorite.

 

Remarks

This structure is used by the Favorite API functions.

In case of ACAPI_Favorite_Get and ACAPI_Favorite_Change functions you just have to set the name field for identifying the Favorite and set which optional fields do you want to retrieve/change.

Do not forget to call ACAPI_DisposeElemMemoHdls for the memo and memoMarker fields if you set them and they are not needed any more.

The API_FavoriteFolderHierarchy type is a typedef of GS::Array<GS::UniString>.

 

Example


// -----------------------------------------------------------------------------
// Change favorite named "Favorite_Test"
//  - set it's ID string to "[Changed]"
// -----------------------------------------------------------------------------

static void     Do_ChangeFavorite (void)
{
    GSErrCode           err;
    API_Favorite        favorite ("Favorite_Test");

    favorite.memo.New ();
    BNZeroMemory (&favorite.memo.Get (), sizeof (API_ElementMemo));
    favorite.memo->elemInfoString = new GS::UniString ("[Changed]");

    ACAPI_WriteReport ("### Favorite_Test Do_ChangeFavorite ###", false);

    err = ACAPI_Favorite_Change (favorite, nullptr, APIMemoMask_ElemInfoString);
    if (err != NoError) {
        if (err == APIERR_BADNAME)
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed because bad name was given", false);
        else if (err == APIERR_NOTMINE)
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed because the given favorite does not belong to the client", false);
        else
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed", false);
    } else {
        ACAPI_WriteReport ("ACAPI_Favorite_Change successfully changed favorite named \"%T\"", false, favorite.name.ToPrintf ());
    }

    ACAPI_DisposeElemMemoHdls (&favorite.memo.Get ());

    return;
}       /* Do_ChangeFavorite */
For further informations and examples, please see the documentation of the related Favorite API functions or the Favorite_Test example Add-On.

 

Requirements

Version: API 23 or later
Header: APIdefs_Favorite.h

 

See Also

ACAPI_Favorite_Get,
ACAPI_Favorite_Create,
ACAPI_Favorite_Change,
ACAPI_Favorite_Read,
API Types