ACAPI_​Favorite_​Change

Changes an existing Favorite (identifed by name).

    GSErrCode  ACAPI_Favorite_Change (
        const API_Favorite&    favorite,
        const API_Element*     elementMask = nullptr,
        UInt64                 memoMask = 0
    );

 

Parameters

favorite
[in] The Favorite entry settings.
elementMask
[in] Optional parameter for masking the relevant fields of favorite.element.
memoMask
[in] Optional parameter for specifying the relevant parts of the favorite.memo parameter.

 

Return Values

NoError
The function has completed with success.
APIERR_BADNAME
Invalid name given (there is no Favorite with the given favorite.name).
APIERR_GENERAL
The Favorites list entry could not be changed.
APIERR_BADPARS
Invalid element given (invalid library part ID), or a marker was given with an element that is not an object.
APIERR_BADCLASSIFICATION
One of the specified classification items is not available for the given element.

For other common API errors see the API Errors document.

 

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 \"%s\"", false, favorite.name.ToCStr ().Get ());
    }

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

    return;
}       /* Do_ChangeFavorite */
For more detailed examples, please see the Favorite_Test example Add-On.

 

Requirements

Version: API 23 or later
Header: ACAPinc.h

 

See Also

ACAPI_Favorite_Rename,
ACAPI_Favorite_Create,
ACAPI_Favorite_Delete,
ACAPI_Favorite_Export,
ACAPI_Favorite_Get,
ACAPI_Favorite_GetNum,
ACAPI_Favorite_Import,
ACAPI_Favorite_Read,

API Functions