Renames an existing Favorite (identifed by name).

    GSErrCode  ACAPI_Favorite_Rename (
        const GS::UniString&    oldName,
        const GS::UniString&    newName
    );

 

Parameters

oldName

[in] The name of the existing Favorite entry.

newName

[in] The new name.

 

Return Values

NoError

The function has completed with success.

APIERR_BADNAME

Invalid name given (empty name is invalid, or there is no Favorite with the given oldName).

APIERR_GENERAL

The Favorites list entry could not be changed.

APIERR_NAMEALREADYUSED

newName is already used as a Favorite name.

For other common API errors see the API Errors document.

 

Example

// -----------------------------------------------------------------------------
// Rename favorite named "Favorite_Test"
//  - appends "[Renamed]" to it's name
// -----------------------------------------------------------------------------

static void     Do_RenameFavorite (void)
{
    GSErrCode           err;
    GS::UniString       oldName = "Favorite_Test";
    GS::UniString       newName = oldName + " [Renamed]";

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

    err = ACAPI_Favorite_Rename (oldName, newName);
    if (err != NoError) {
        if (err == APIERR_BADNAME)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because bad name was given", false);
        if (err == APIERR_NAMEALREADYUSED)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because the new name is alerady in used", false);
        else if (err == APIERR_NOTMINE)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because the given favorite does not belong to the client", false);
        else
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed", false);
    } else {
        ACAPI_WriteReport ("ACAPI_Favorite_Rename successfully renamed favorite \"%s\" to \"%s\"", false, oldName.ToCStr ().Get (), newName.ToCStr ().Get ());
    }

    return;
}       /* Do_RenameFavorite */

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_Change,
ACAPI_Favorite_Create,
ACAPI_Favorite_Delete,
ACAPI_Favorite_Export,
ACAPI_Favorite_Get,
ACAPI_Favorite_GetNum,
ACAPI_Favorite_Import,
ACAPI_Favorite_Read,

API Functions