Creates a Unique AddOnObject.
GSErrCode ACAPI_AddOnObject_CreateUniqueObject (
const GS::UniString& objectName,
API_Guid* objectGuid
);
Parameters
- objectName
- [in] The name of the Unique AddOnObject.
- objectGuid
- [out] The GUID of the created object. Value is undefined if an error happened.
Return Values
NoError- The function has completed with success.
APIERR_CANCEL- If the user refused to Send & Receive all changes.
APIERR_NAMEALREADYUSED- If there is already a Unique AddOnObject with the given objectName.
APIERR_NOTEAMWORKPROJECT- Indicates that the project is an Offline TeamWork project. Due to possible conflicts, it is not allowed to create Unique AddOnObjects in an Offline Teamwork Project.
APIERR_SERVICEFAILED- The created Unique AddOnObject could not be sent to the TeamWork server.
For other common API errors see the API Errors document.
Remarks
Unique AddOnObjects were introduced to support more restricted but safer TeamWork behaviour. Because multiple general (non-unique) AddOnObjects can exist with the same name, in TeamWork it could happen that two users created “the same” AddOnObject simultaneously, but at the end they ended up with two different AddOnObjects. This led to a lot of confusion.
With Unique AddOnObjects – like general AddOnObjects – you can store custom data in the project database. However – unlike general AddOnObjects – their names must be and will be unique among each other. Please note that names of a Unique AddOnObject and general AddOnObjects may be equal.
In a TeamWork project creating Unique AddOnObjects will result in a Full Receive and a Full Send to ensure project consistency. Due to this inconvenience, it is possible to create more Unique AddOnObjects at once with the ACAPI_AddOnObject_CreateUniqueObjectMore function.
Unlike general AddOnObjects – to ensure no data conflict occurs – it is not possible to give default content to a Unique AddOnObject. To do so, you must call ACAPI_AddOnObject_ModifyObject function.
The stored data can be accessed using the returned objectGuid. All functions that work for general AddOnObjects work for Unique AddOnObjects, too, except ACAPI_AddOnObject_GetObjectGuidFromName: to get the GUID of a Unique AddOnObject from its name use ACAPI_AddOnObject_GetUniqueObjectGuidFromName instead.
Requirements
- Version: API 21 or later
- Header: ACAPinc.h