Solaris Common Desktop Environment: Programmer's Guide

Data-Typing Functions

To look up an attribute for a data object, you must first determine the type of the object and then ask for the appropriate attribute value for that type. The functions that you can use to query the database for data information are shown in Table 9-4. Each of these functions has a man page in section (3). Refer to the appropriate man page for more information.

Table 9-4 Data-Typing Database Query Functions


Function	Description
`DtDtsBufferToAttributeList()`	Finds the list of data attributes for a given buffer.
`DtDtsBufferToAttributeValue()`	Finds the data attribute for a given buffer.
`DtDtsBufferToDataType()`	Finds the data-type name for a given buffer.
`DtDtsDataToDataType()`	Finds the data type for a given set of data.
`DtDtsDataTypeIsAction()`	Returns the resulting saved data type for the directory.
`DtDtsDataTypeNames()`	Finds a complete list of available data types.
`DtDtsDataTypeToAttributeList()`	Finds the attribute list for a given data attribute name.
`DtDtsDataTypeToAttributeValue()`	Finds the attribute value for a given data attribute name.
`DtDtsFileToAttributeList()`	Finds the list of data attributes for a given file.
`DtDtsFileToAttributeValue()`	Finds the data attribute value for a given file.
`DtDtsFileToDataType()`	Finds the data type for a given file.
`DtDtsFindAttribute()`	Finds the list of data types where attribute `name` matches `value`.
`DtDtsFreeAttributeList()`	Frees the memory of the given attribute list.
`DtDtsFreeAttributeValue()`	Frees the memory of the given attribute value.
`DtDtsFreeDataType()`	Frees the application memory for the given data-type name.
`DtDtsFreeDataTypeNames()`	Releases memory created with the `DtDtsDataTypeNames()` or `DtDtsFindAttribute()` call.
`DtDtsIsTrue()`	A convenience function that converts a string to a Boolean.
`DtDtsRelease()`	Unloads the data-typing database information, generally in preparation for a reload.
`DtDtsSetDataType()`	Sets the data type for the specified directory.
`DtsLoadDataTypes()`	Initializes and loads the database fields for the data-typing functions. Use instead of `DtDbLoad()` when you do not need to use actions or action types and you need extra performance. Use `DtDbLoad()` when you need to use actions.

You can type data and retrieve attributes in one of three ways: simple, intermediate, or advanced.

Simple Data Typing

The simplest way to type data is to use the following functions:

DtDtsFileToAttributeList()
DtDtsFileToAttributeValue()

When you use these functions, a file is typed and a single attribute, or the entire list, is retrieved. System calls are made, data is typed, and the attribute is retrieved. These functions call the intermediate data-typing functions.

DtDtsBufferToAttributeList()
DtDtsBufferToAttributeValue()

Buffers are assumed to have a mode that matches regular files that have read/write permissions. See "Advanced Data Typing" to type read-only buffers.

Intermediate Data Typing

When you type data and retrieve attributes, the data-typing part of the process is the most expensive in terms of performance. You can type data in a second way that improves performance by separating the data-typing and attribute-retrieval functions. Use the following functions for intermediate data typing:

DtDtsBufferToDataType()
DtDtsFileToDataType()
DtDtsDataTypeToAttributeList()
DtDtsDataTypeToAttributeValue()

Use these functions if your application queries for more than a single attribute value. When you use these functions, an object is typed and then that type is used to retrieve one or more attributes from the attribute list.

Using the intermediate data-typing functions is the recommended way to type data and retrieve attributes. These functions call the advanced data-typing functions and make the same assumptions about buffers as the simpler data typing.

Advanced Data Typing

Advanced data typing separates system calls, data typing, and attribute retrieval even further. Advanced data typing is more complicated to code because it uses data from existing system calls, which are initialized in advance and are not included as part of the data-typing function. Use the following function for advanced data typing:

DtDtsDataToDataType()

To type a read-only buffer, a stat structure should be passed that has the st_mode field set to S_IFREG | S_IROTH | S_IRGRP | S_IRUSR.

Data Types That Are Actions (DtDtsDataTypeIsAction)

For every action in a database a synthetic data type is generated when a database is loaded that allows actions to be typed. These data types may have two additional attributes:

IS_ACTION is a string-Boolean value that tells users of this data type that it is an action. If IS_ACTION is set to the string true (independent of case), the data is an action.

IS_SYNTHETIC is a string-Boolean value that tells users of this data type that it was generated from an entry in the ACTION table. If IS_SYNTHETIC is set to true, the data type was generated.