C++ Syntax

bool

MKI_ProfileDrawingSetData(

__int16 f_nOwnerID,

__int32 f_nProfileID,

const void* const f_pProfileData,

const size_t f_unSize );

Stores a plug-in's binary data profile in a drawing.

Parameters

OwnerID

[__int16] This value is a unique identification of the creator of the plug-in. The value MKI_DB_OWNER_MK is reserved for use by Malz++Kassner. Valid range: 0 <= Value < 10000.

Third-party vendors that plan to implement a plug-in should contact Malz++Kassner to receive their unique identification (see Getting Your Private Owner ID).

ProfileID

[__int32] This value is used to identify the profile for further access. Each plug-in creator can use the full range of the value, as it is used in combination with his OwnerID. Usually, this value will be equal to the plug-in's ID.

As this value is a 32bit value (rather than being a 16bit value like the plug-in's ID), each plug-in can store multiple profiles. In order to do so, store the plug-in's ID in the low-word of ProfileID, and an additional number in its high-word.

ProfileData

[const void* const] Address of a buffer that contains the profile data. This profile data will internally be stored in a list of binary data blocks.

This profile data will replace a possibly existing profile entry with the same OwnerID and ProfileID. If the value of ProfileData is nullptr, only a possibly existing profile entry in the drawing will be deleted without adding a new entry.

Size

[const size_t] Size of the profile data pointed to by ProfileData. If ProfileData is not nullptr and the value of Size is less or equal to zero, the procedure will fail. If ProfileData is nullptr, the value of Size will be ignored. Valid range: 0 < Value <= 64000.

Return Value

Returns true if the profile was stored successfully, else false (indicating out-of-memory).

Comment

In order to keep track of several versions, we strongly recommend that the data stored as profile contains a unique identifier that allows the plug-in to know which plug-in version created that profile data. We usually add a time stamp as first element to each structure we store in the registry:

class CProfileData

{

public:

MKI_STR32A m_szTimeStamp;

// ...Further Structure Elements...

};

Inside the plug-in, the time stamp is defined as a string that is updated each time the structure CProfileData is changed. A standard time stamp might be:

constexpr LPSTR MY_PLUGIN_ID = "1.00-2022-06-01";

This is the time stamp of version 1.00, the last change was on April 1, 2021.

When saving a profile, the TimeStamp element should be initialized with MY_PLUGIN_ID. When reading a profile, the plug-in can use the TimeStamp element to verify whether it can interpret this data or not. If not, the plug-in may silently use the default settings without further notice to the user.