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

Parameters

Return Values

Example

Requirements

See Also