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