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
For more detailed examples, please see the Favorite_Test example Add-On.// ----------------------------------------------------------------------------- // 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 */
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