Function CDM_CreateAttribute


Definition:#include <CDM.h>
Prototype:CDM_Attribute CDM_CreateAttribute(char *Name, CDM_AttributeValue Value);
Arguments:

Name: The name of the Attribute. (char *)
Value: The value of the Attribute. (CDM_AttributeValue)

C/C++ API Sections
Tcl API Sections
Description
Return Value
Notes
See Also
Index

Description:

This function will create and return an Attribute object (of type CDM_Attribute). In order to reduce memory requirements, this function will try to locate if an Attribute with exactly the same characteristics (same Name and Attribute value of the same type and value) already exists. In such a case, this (possibly shared) Attribute object will be returned. Else, a new Attribute object will be created and returned.

Special attention should be given to the Attribute value object (specified by the "Value" parameter) so as not to leak memory. This function internally will always increase and then decrease the reference count of this object, meaning that this object may be freed if it has a reference count of 0. If the caller wants to preserve a reference to this object, so as to free it at a later stage through CDM_Free or Tcl_DecrRefCount, Tcl_IncrRefCount should be called be called before CDM_CreateAttribute is called. The value of the "Name" parameter will not be modified or referenced in any way, as CDM will create and manipulate a local copy of this value.

Return Value:

This function will return an Attribute object (of type of CDM_Attribute). This object may be an old, already in use (shared) object or a newly created object, according to the specified parameters.

In case of an error, NULL will be returned and an error message describing the error will be left at the current Tcl interpreter (CDM_Interp). In such a case, the object described by the "Value" parameter won't be altered in any way, leaving the responsibility to free it to the caller.

Notes:

Note that the object specified by the "Value" parameter will be freed, if it has a reference count equal to 0. If the caller wants to ensure that this object won't be freed by this function, Tcl_IncrRefCount must be used. Then the caller is responsible to free the object later with a call to either CDM_Free or Tcl_DecrRefCount. This behaviour has been chosen in order to avoid memory leakage when using code like the following example:
CDM_CreateAttribute("name", CDM_CreateAttributeValue(CDM_STRING, "value"));

This function is equivelant to tip_CreateAttribute (Tcl API).

See Also:

tip_CreateAttribute


Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.