9 Accessing the Data-Typing Database

Contents of Chapter:
Summary
Library and Header Files
Demo Program
Data Criteria and Data Attributes
Data-Typing Functions
Simple Data Typing
Intermediate Data Typing
Advanced Data Typing
Data Types That Are Actions (DtDtsDataTypeIsAction)
Registering Objects as Drop Zones
Example of Using the Data-Typing Database
This chapter describes the data-typing functions and how to use the data- typing database.

Summary

Data typing provides an extension to the attributes of files and data beyond what is provided by the traditional UNIX file systems. These extensions consist of attributes, such as icon names, descriptions, and actions, that can be performed on files and data. This information is stored in name/value pairs in the DATA_ATTRIBUTES table (or database). The desktop uses a certain set of DATA_ATTRIBUTES, described in the following paragraphs. The DATA_ATTRIBUTES table is extendable for future and application-specific growth, although extending this table is not recommended because other applications may not check the additions.

Data is matched with a specific file or data entry in a DATA_CRITERIA table. The DATA_CRITERIA table entries are sorted in decreasing order from most specific to least specific. For example, /usr/lib/lib* is more specific than /usr/* and would, therefore, appear first. When a request to type a file or data is made, the table is checked in sequence to find the best match using the information provided either from the file or from the data. When an information and entry match is found, DATA_ATTRIBUTES_NAME is used to find the proper DATA_ATTRIBUTES entry.

If you want your application to present data objects (either files or data buffers) to the user in a manner consistent with the desktop, use the DtDts* API to determine how to display the data objects and how to operate on them. For example, your application can determine the icon that represents a data object by calling the DtDtsDataTypeToAttributeValue function for the ICON attribute.

Library and Header Files

To use data typing, you need to link to the libDtSvc library. Actions are usually loaded with the data-typing information. Actions require links to the libXm and libX11 libraries. The header files are Dt/Dts.h and Dt/Dt.h.

Demo Program

A demo program containing an example of how to use the data-typing database is in /usr/dt/examples/dtdts/datatypes/datatyping.c.

Data Criteria and Data Attributes

Data typing consists of two parts:

The attributes of data criteria, in alphabetical order, are:

Table 9-1 describes the data criteria in the order in which you are most likely to use them.

Table 9-1:  Data Criteria in Order of Most Likely Use

Criteria Description Typical Usage
DATA_ATTRIBUTES_NAME The name of this type of data. The value is a record_name in the data attributes table. POSTSCRIPT
NAME_PATTERN A shell pattern-matching expression describing the file names that could match this data. The default is an empty string, which means to ignore file patterns in matching. *.ps
CONTENT Three values that are interpreted as the start, type, and value fields of the magic file used by the file utility. See the file(1) man page for more information. The default is an empty field, which means to ignore contents in matching. The following types are examples of what can be matched: string, byte, short, long, and file name. 0 string !%
MODE A string of zero to four characters that match the mode field of a stat structure. See the stat(2) man page for more information. The first character indicates:

d matches a directory
s matches a socket
l matches a symbolic link
f matches a regular file
b matches a block file
c matches a character special file

The characters listed below can be either the first or subsequent characters:

r matches any file with any of its user, group, or other read permission bits set.
w matches any file with any of its user, group, or other write permission bits set.
x matches any file with any of its user, group, or other execute or directory-search permission bits set.

For example the MODE field of frw matches any regular file that is readable or writable; x matches any file with any of its executable or search bits set. The default is an empty field, which means to ignore the mode in matching.

 f&!x
PATH_PATTERN A shell pattern-matching expression describing the absolute path names that could match this data. The default is an empty string, which means to ignore path patterns in matching. */mysubdir/*
LINK_NAME See dtdtsfile(4) man page.  
LINK_PATH See dtdtsfile(4) man page.  

Some of the more common attributes of data types, in alphabetical order, are:

Table 9-2 describes the data attributes in the order in which you are most likely to use them.

Table 9-2:  Data Attributes in Order of Most Likely Use

Attribute Description Typical Usage
DESCRIPTION A human-readable description of this data. If this field is NULL or is not included in the data attribute record, the name of the data attribute should be used. This is a PostScript page description
ICON The name of the icon to be sued for this data. If this field is NULL or is not included in the data attribute record, the standard icon should be used. See dtdtsfile(4) for more details on icon naming. Dtps
PROPERTIES Keywords to indicate properties for this data. Valid values are invisible and visible. If this field is NULL or is not included in the data attribute record, the visible property should be assumed. Use this if you want to completely hide files from the user. invisible
ACTIONS A list of actions that can be performed on this data. The list refers to names in the action table for actions that are to be presented of the user for objects of this type. If this field is NULL or is not included in the data attribute record, no action is available. Open, Print
NAME_TEMPLATE Field A string used to create a new file for data of this type. The string is passed to sprintf(3) with the file name as the single argument. The default is empty. Contrast this field with the NAME_PATTERN field of the data criteria table in that the template is used to create a specific file, such as %s.c, whereas the pattern is used to find files, such as *.c. %s.ps
IS_EXECUTABLE Field A string-Boolean value that tells users of this data type that it can be executed as an application. If IS_EXECUTABLE is set to true (see DtDtsIsTrue()) the data is executable. If this field is NULL, is not included in the data attribute record, or is not set to true, then the data is considered not executable. true
MOVE_TO_ACTION The name of an action to be invoked when an object is moved to the current object. FILESYSTEM_MOVE
COPY_TO_ACTION The name of an action to be invoked when an object is copied to the current object. FILESYSTEM_COPY
LINK_TO_ACTION The name of an action to be invoked when an object is linked to the current object. FILESYSTEM_LINK
IS_TEXT A string-Boolean value that tells users of this data type that it is suitable for manipulation (viewing or editing) in a text editor or text widget. The IS_TEXT field is set to true (see DtDtsIsTrue()) if the data is textual in nature and if it should be presented to the user in text form. Criteria for making this determination include whether data consists of human language, is generated and maintained manually, is usefully viewable and editable in a text editor, or contains no (or only minimal) structuring and formatting information.

If the IS_TEXT field is true, the data is eligible to be displayed directly by an application. That is, the application can load the data directly into a text editing widget, sicih as XmText.

 See Table 9-3 for examples.
MEDIA Field The names in the MEDIA name space describe the form of the data itself. MEDIA names are used as ICCCM selection targets, named in the MEDIA field of the data-type records, and used in the type parameter of ToolTalk Media Exchange messages.

The MEDIA name space is a subset of the name space of selection target atoms as defined by the ICCCM. All selection targets that specify a data format are valid MEDIA names, and all valid MEDIA names can be used directly as selection targets. Some selection targets specify an attribute for the selection (for example, LIST_LENGTH) or a side effect to occur (for example, DELETE), rather than a data format. These attribute selection targets are not part of the MEDIA name space.

 POSTSCRIPT
MIME_TYPE MEDIA is the desktop internal, unique name for data types. However, other external naming authorities have also established name spaces. Multipurpose Internet Message Extensions (MIME), as described in the referenced MIME RFC, is one of those external registries, and is the standard-type name space for the desktop mailer. application/
postscript
X400_TYPE X.400 types are similar in structure to the MEDIA type, but are formatted using different rules and have different naming authorities. 1 2 840 113556 3 2 850
INSTANCE_ICON Field The name of the icon to be used for this instance of data, typically a value such as %name%.icon [Bug in dtdtsfile(4) manpage, too]. If INSTANCE_ICON is set, the application should use it instead of ICON. If this field is NULL or is not included in the data attribute record, the ICON field should be used. myicondir/%name%.bm
DATA_HOST The DATA_HOST attribute is not a field that can be added to the data attributes table in the *.dt file, but it may be returned to an application reading attributes from the table. The data-typing service adds this attribute automatically to indicate the host system from which the data type was loaded. If this field is NULL or is not included in the data attribute record, the data type was loaded from the local system.  

The IS_TEXT field differs from the text attribute of the MIME_TYPE field, which is the MIME content type, as described in the referenced MIME_ RFC. The MIME content type determines whether the data consists of textual characters or byte values. If the data consists of textual characters, and the data is labeled as text/*, the IS_TEXT field determines whether it is appropriate for the data to be presented to users in textual form.

Table 9-3 shows some examples of IS_TEXT usage with different MIME_TYPE attributes.

Table 9-3:  IS_TEXT Attribute Examples

Description and MIME_TYPE Attribute IS_TEXT Value
Human language encoded in ASCII with MIME_TYPE text/plain IS_TEXT true
Human language encoded in E*UC, JIS, Unicode, or an ISO Latin charset with MIME_TYPE text/plain; charset=XXX IS_TEXT true
CalendarAppointmentAttrs with a MIME_TYPE text/plain IS_TEXT false
Hypertext Markup Language (HTML) with a MIME_TYPE text/html IS_TEXT true
PostScript with MIME_TYPE application/postscript IS_TEXT false
C program source (C_SRC) with MIME_TYPE text/plain IS_TEXT true
Bitmaps and pixmaps (XBM and XPM) with MIME_TYPE text/plain IS_TEXT false
Project or module files for the desktop application building service with MIME_TYPE text/plain IS_TEXT false
Shell scripts with MIME_TYPE text/plain IS_TEXT false
Encoded text produced by uuencode(1) with MIME_TYPE text/plain IS_TEXT false
*MIME_TYPE text/plain IS_TEXT false

See the dtdtsfile(4) man page for more information about data-type attributes.

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 a 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:

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.

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:

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:

Registering Objects as Drop Zones

If your application defines data types, follow these steps to ensure that it provides all the drag and drop behavior that you intend:

  1. In your application, decide if you need to define any data types.

  2. For each data type you define, decide whether you want the associated object to be a drop zone.

  3. For each object that you want to register as a drop zone, decide which operations--move, copy, or link--you want to define.

  4. For the drop operations that are valid for each object, define the appropriate drop actions (set the MOVE_TO_ACTION, COPY_TO_ACTION, and LINK_TO_ACTION attributes).

If your application displays icons for data objects, you may choose to support those icons as drop zones. If so, you need to query the MOVE_TO_ACTION, COPY_TO_ACTION, or LINK_TO_ACTION attributes to determine the drop behavior for those data objects. Objects should support drop operations only if the corresponding attribute value is not NULL. If all three attributes have NULL values, the object should not be registered as a drop site. Whenever you set at least one of these attributes for an object with a defined data type, your application registers that object as a drop zone.

When a user drags an object to a drop zone, your application determines which gesture (that is, which drag operation) was used to make the drop. Based on the drag operation and the drop zone's data type, the application retrieves a drop attribute from the data-typing database. It then calls DtActionInvoke, using the following two rules to determine its parameters:

  1. If the user drops objects A and B onto object C, call DtActionInvoke with C, A and B as args. The action is the value of either MOVE_TO_ACTION, COPY_TO_ACTION, LINK_TO_ACTION of C. If object C is an action, the args list does not include C. Also, the action is C.

The File Manager, along with its directory and folder objects, exemplifies how the desktop uses the move, copy, and link drop attributes. A user can drag and drop objects (files) to directory folders. File Manager defines MOVE_TO_ACTION, COPY_TO_ACTION, and LINK_TO_ACTION actions for folder objects. These actions perform the appropriate file system move, copy, and link system functions.

See /usr/dt/appconfig/types/C/dtfile.dt for an example of how to define the MOVE_TO_ACTION, COPY_TO_ACTION, and LINK_TO_ACTION attributes. See Chapter 5, "Integrating with Drag and Drop," for information about how to use drag and drop.

Example of Using the Data-Typing Database

This section contains example code of how to use data typing. You can find this example code in /usr/dt/examples/dtdts/datatyping.c. The example code displays the data type, icon name, and supported actions for each file passed to it. You can then use the dtaction client to run a supported action on the file. The usage for datatyping is:

datatyping file1 [file2 ...]

#include <Xm/Form.h>
#include <Xm/Text.h>
#include <Dt/Dts.h>

#define ApplicationClass "DtDatatyping"

static Widget text;

static void DisplayTypeInfo(int, char**);

int main(int argc, char **argv)
{
    XtAppContext appContext;
    Widget toplevel, form;
    Arg args[20];
    int n;

    toplevel = XtAppInitialize(&appContext, ApplicationClass,
    NULL,  0,
        argc, argv, NULL, NULL, 0);

    if (argc == 1) {
        printf("%s: No files specified.\n", argv[0]);
        exit(1);
    }

    form = XmCreateForm(toplevel, "form", NULL, 0);
    XtManageChild(form);
    n = 0;
    XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNtopAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM); n++;
    XtSetArg(args[n], XmNeditable, False); n++;
    XtSetArg(args[n], XmNeditMode, XmMULTI_LINE_EDIT); n++;
    XtSetArg(args[n], XmNrows, 25); n++;
    XtSetArg(args[n], XmNcolumns, 90); n++;
    text = XmCreateScrolledText(form, "text", args, n);
    XtManageChild(text);

    XtRealizeWidget(toplevel);

    if (DtAppInitialize(appContext, XtDisplay(toplevel), toplevel,
        argv[0], ApplicationClass) == False) {
        printf("%s: Couldn't initialize Dt\n", argv[0]);
        exit(1);

    }

    DtDbLoad();
    DisplayTypeInfo(argc, argv);
    XtAppMainLoop(appContext);

}

static void DisplayTypeInfo(int argc, char **argv)
{
    char *file;
    char *datatype;
    char *icon;
    char *actions;
    char str[100];
    int i;

    sprintf(str, "%-30s\t%-10s\t%-8s\t%-20s\n",
                "File",
                "DataType",
                "Icon",
                "Actions");
    XmTextInsert(text, XmTextGetLastPosition(text), str);

    sprintf(str, "%-30s\t%-10s\t%-8s\t%-20s\n",
                "-------------------",
                "--------",
                "----",
                "-------");
    XmTextInsert(text, XmTextGetLastPosition(text), str);

    for(i=1; i < argc; i++) {
       char *file = argv[i];

       /* find out the Dts data type */
       datatype = DtDtsFileToDataType(file);

       if(datatype) {
          /* find the icon attribute for the data type */
          icon = DtDtsDataTypeToAttributeValue(datatype,
                 DtDTS_DA_ICON, file);
           }

       /* Directly find the action attribute for a file */
       actions = DtDtsFileToAttributeValue(file,
           DtDTS_DA_ACTION_LIST);

       sprintf(str, "%-30s\t%-10s\t%-8s\t%s\n",
                        file,
                        datatype?datatype:"unknown",
                        icon?icon:"unknown",
                        actions?actions:"unknown");
       XmTextInsert(text, XmTextGetLastPosition(text), str);

        /* Free the space allocated by Dts */

       DtDtsFreeAttributeValue(icon);
       DtDtsFreeAttributeValue(actions);
       DtDtsFreeDataType(datatype);
    }
}