Home / Autodocs / datatypes.library
NAME
- ObtainDataTypeA
-
Examines a handle and return its DataType. (V39)
SYNOPSIS
dtn = ObtainDataTypeA (type, handle, attrs);
d0 d0 a0 a1
struct DataType *ObtainDataTypeA (ULONG, APTR, struct TagItem *);
dtn = ObtainDataType (type, handle, tag1, ...);
struct DataType *ObtainDataType (ULONG, APTR, Tag tag1, ...);
d0 d0 a0 a1
struct DataType *ObtainDataTypeA (ULONG, APTR, struct TagItem *);
dtn = ObtainDataType (type, handle, tag1, ...);
struct DataType *ObtainDataType (ULONG, APTR, Tag tag1, ...);
FUNCTION
This function examines the data that the handle points to, and returns a DataType record that describes the data.
INPUTS
- type
-
Type of handle.
- handle
-
Handle to examine. For DTST_FILE, handle must be BPTR lock.
For DTST_CLIPBOARD, handle must be struct IFFHandle *.
For DTST_MEMORY, handle will be ignored (you need to specify the additional information required by this source type through the attrs list).
- attrs
-
Additional attributes (see TAGS).
TAGS
- 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).
NOTES
The datatypes.library maintains a sorted list of all the DataType descriptors. The descriptor can consist of a function, a data mask for the first 64 bytes of the data, and a name pattern.
The sort order for the list is:
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 sort order for the list is:
Descriptors with a function and no mask or name pattern.
Descriptors with a function and a mask or name pattern.
Descriptors with no function and a mask or name pattern.
Within each group, they are also sorted in descending priority and descending mask length.
Descriptors with a function and a mask or name pattern.
Descriptors with no function and a mask or name pattern.
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.
RESULT
Success returns a pointer to a DataType. You must call ReleaseDataType() when you are done with the handle.
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_NO_FREE_STORE
-
Not enough memory.
- ERROR_OBJECT_NOT_FOUND
-
Unable to open the data object.
- ERROR_NOT_IMPLEMENTED
-
Unknown handle type.