Returns the stored preferences of the add-on.

    GSErrCode  ACAPI_GetPreferences_Platform (
        Int32*              version,
        GSSize*             nByte,
        void*               data,
        unsigned short*     platformSign
    );

 

Parameters

version

[out] On return contains the version of the stored preferences, or 0 if no preferences were found.

nByte

[out] On return contains the size of the stored preferences in bytes, or 0 if no preferences were found.

data

[in/out] On return contains the stored preferences.

platformSign

[out] On return contains the platform identifier of the stored preferences.

 

Return Values

For common API errors see the API Errors document.

 

Remarks

Use this function to retrieve the preferences data stored into the preferences or the plan file currently opened. The preferences could have been saved into the plan on the other platform; in this case it is your responsibility to convert data structures stored in opposite byte order.

All the parameters can be nullptr.

The data pointer should be allocated and disposed by the add-on, thus first you should call this function to retrieve only the version number and the size of the preferences data.

 

Example

Int32           version = 0;
GSSize          nBytes = 0;
GSPtr           pref;
unsigned short  platformSign = GS::Act_Platform_Sign;

ACAPI_GetPreferences_Platform (&version, &nBytes, nullptr, nullptr);      // get version and size
if (version == MY_PREFERENCES_VERSION) {                            // check version
    pref = BMAllocatePtr (nBytes, ALLOCATE_CLEAR, 0);               // allocate memory for preferences
    if (pref != nullptr) {
        ACAPI_GetPreferences_Platform (&version, &nBytes, pref, &platformSign);     // get actual preferences
        if (platformSign != GS::Act_Platform_Sign) {
            // swap the necessary bytes
        }

        // do something with the preferences data
        BMKillPtr (&pref);                                          // dispose the allocated pointer
    }
}

 

Requirements

Version: API 6.1 or later

Header: ACAPinc.h

 

See Also

Saving Add-On data into the Preferences and the Project File
ACAPI_GetPreferences
ACAPI_SetPreferences
ACAPI_SetPreferences_OldVersion
API Functions