Home / Autodocs / datatypes.library
NAME
- NewDTObjectA
-
Create an data type object. (V39)
SYNOPSIS
o = NewDTObjectA (name, attrs);
d0 d0 a0
Object *NewDTObjectA (APTR, struct TagItem *);
o = NewDTObject (name, tag1, ...);
Object *NewDTObject (APTR, Tag tag1, ...);
d0 d0 a0
Object *NewDTObjectA (APTR, struct TagItem *);
o = NewDTObject (name, tag1, ...);
Object *NewDTObject (APTR, Tag tag1, ...);
FUNCTION
This is the method for creating datatype objects from 'boopsi' classes. Boopsi' stands for "basic object-oriented programming system for Intuition".)
You further specify initial "create-time" attributes for the object via a TagItem list, and they are applied to the resulting datatype object that is returned.
You further specify initial "create-time" attributes for the object via a TagItem list, and they are applied to the resulting datatype object that is returned.
INPUTS
- name
-
Name of the data source. Usually an existing file name.
- attrs
-
Pointer to a taglist containing additional arguments.
TAGS
- DTA_SourceType
-
Specify the type of source data; such as coming from a file or clipboard (defaults to DTST_FILE). If source type is clipboard, then the name field contains the numeric clipboard unit. If source type is DTST_MEMORY, the name field will be ignored (V44).
- DTA_Handle
-
Can optionally be used instead of the name field. Must be a valid file lock if DTA_SourceType is DTST_FILE. Must be a valid IFFHandle if DTA_SourceType is DTST_CLIPBOARD. Will be ignored if DTA_SourceType is DTST_MEMORY.
- NOTE:
-
If you provide a file lock if DTA_SourceType is DTST_FILE then this file lock will become associated with the data type object. Do not UnLock() it, or freeing the data type object will result in the same lock being unlocked again!
If you provide a file lock on a file, you must also provide the name of the file or it will fail to open. This makes the use of the DTA_Handle difficult to justify for this use case.
- DTA_DataType
-
Specify the class of data. Data is a pointer to a valid DataType. This is only used when attempting to create a new object that doesn't have any source data.
- DTA_GroupID
-
Specify that the object must be of this type, or NewDTObject() will fail with IoErr() of ERROR_OBJECT_WRONG_TYPE.
- DTA_SourceAddress (APTR)
-
For DTST_MEMORY source data, this specifies the memory address at which the source data is located. This must be non-NULL. This attribute is required for DTST_MEMORY source data (V44).
- DTA_SourceSize (ULONG)
-
For DTST_MEMORY source data, this specifies the size of the source data (in bytes). This must be greater than 0. This attribute is required for DTST_MEMORY source data (V44).
within the destination window.
- GA_ID
-
Specify the object ID.
- GA_UserData
-
Specify the application specific data for the object.
RESULT
A boopsi object, which may be used in different contexts such as a gadget or image, and may be manipulated by generic functions. You eventually free the object using DisposeDTObject().
A NULL return indicates failure. Use IoErr() to get error value. Following is a summary of the error number used and there meaning as it relates to DataTypes.
A NULL return indicates failure. Use IoErr() to get error value. Following is a summary of the error number used and there meaning as it relates to DataTypes.
- ERROR_REQUIRED_ARG_MISSING
-
Indicates that a required attribute wasn't passed in.
- ERROR_BAD_NUMBER
-
An invalid group ID was passed in.
- ERROR_OBJECT_WRONG_TYPE
-
Object data type doesn't match DTA_GroupID.
- ERROR_NO_FREE_STORE
-
Not enough memory.
- DTERROR_UNKNOWN_DATATYPE
-
Unable to open the class library associated with the data type.
- DTERROR_COULDNT_OPEN
-
Unable to open the data object.
- ERROR_NOT_IMPLEMENTED
-
Unknown handle type.
NOTES
This function invokes the OM_NEW "method" for the class specified.
The DTST_MEMORY source type introduced in V44 makes in-memory data available to subclasses as if the data were stored in a file. Thus, subclasses will see the data as DTST_FILE. Since the data does not correspond to an on-disk file, subclasses and examine hook code must not assume that they will be able to reopen the "file" whose data has been provided to them.
The DTST_MEMORY source type introduced in V44 makes in-memory data available to subclasses as if the data were stored in a file. Thus, subclasses will see the data as DTST_FILE. Since the data does not correspond to an on-disk file, subclasses and examine hook code must not assume that they will be able to reopen the "file" whose data has been provided to them.
EXAMPLE
STRPTR fileName = "s:startup-sequence"
Object *o;
/* Simplest use is to just open an existing file */
if (o = NewDTObject ((APTR)fileName, NULL))
{
}
Object *o;
/* Simplest use is to just open an existing file */
if (o = NewDTObject ((APTR)fileName, NULL))
{
SEE ALSO
BUGS
Documentation used to state that for DTA_SourceType == DTST_FILE the DTA_Handle tag had to refer to a valid file handle. This is not correct. The DTA_Handle tag for DTA_SourceType == DTST_FILE always had to be a valid file lock.
A file lock used with the DTA_Handle tag and DTA_SourceType == DTST_FILE will become part of the data type object. UnLock()'ing that file lock will cause the same file lock to be UnLock()'ed again, causing memory to be freed twice.
The use of a file lock with DTA_Handle for a file will still require that you also provide the name of the file in question, making it hard to justify its use in the first place.
A file lock used with the DTA_Handle tag and DTA_SourceType == DTST_FILE will become part of the data type object. UnLock()'ing that file lock will cause the same file lock to be UnLock()'ed again, causing memory to be freed twice.
The use of a file lock with DTA_Handle for a file will still require that you also provide the name of the file in question, making it hard to justify its use in the first place.