Returns the stored preferences of the add-on.

    GSErrCode  ACAPI_GetPreferences (
        Int32*      version,
        GSSize*     nByte,
        void*       data
    );

 

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. This parameter can be nullptr.

 

Return Values

For common API errors see the API Errors document.

 

Remarks

(1) You can retrieve the stored preferences of your add-on. This information was previously passed onto the add-on as a parameter of the DoCommand function.

(2) Setting the last parameter to nullptr means the API will return only the version number and the size of the preferences data. If the size or the version number is 0, then no preferences were stored.

(3) Version information can be used to convert older preferences to the current format.

  In Archicad use ACAPI_GetPreferences_Platform instead of ACAPI_GetPreferences in order to get the platform identifier of the preferences data.

 

Example

Int32       version;
GSSize      nBytes;
GSPtr       pref;

ACAPI_GetPreferences (&version, &nBytes, nullptr);             // (2) get version and size
if (version == MY_PREFERENCES_VERSION) {                    // (3) check version
    pref = BMAllocatePtr (nBytes, ALLOCATE_CLEAR, 0);       // allocate memory for preferences
    if (pref != nullptr) {
        ACAPI_GetPreferences (&version, &nBytes, pref);     // get actual preferences
        // do something with the preferences data

        BMKillPtr (&pref);                                  // dispose allocated pointer
    }
}

 

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

 

See Also

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