Maintaining Object Specs

The ToolTalk service provides the functions to examine, compare, query, and move object specs. Table 12-2 lists the ToolTalk functions you use to maintain object specs.

Examining Spec Information

You can examine the following spec information with the specified ToolTalk functions:

• Path name of the file that contains the object: tt_spec_file

• Otype of this object: tt_spec_type

• Properties stored on the spec: tt_spec_prop or tt_spec_bprop

Comparing Object Specs

To compare two objids, use tt_objid_equal. tt_objid_equal returns a value of 1 even in the case where one objid is a forwarding pointer for the other.

Querying for Specific Specs in a File

Create a filter function to query for specific specs in a file and obtain the specs in which you are interested.

Use tt_file_objects_query to find all the objects in the named file. As the ToolTalk service finds each object, it calls your filter function, and passes it the objid of the object and the two application-supplied pointers. Your filter function does some computation and returns a Tt_filter_action value (TT_FILTER_CONTINUE or TT_FILTER_STOP) to either continue the query, or to quit the search and return immediately.

Example 12-1 illustrates how to obtain a list of specs.

Example 12-1 Obtaining a List of Specifications

/*
 * Called to update the scrolling list of objects for a file. Uses
 * tt_file_objects_query to find all the ToolTalk objects.
 */
int
cntl_update_obj_panel()
{
       static int list_item = 0;
	char *file;
	int i;

	cntl_objid = (char *)0;

	for (i = list_item; i >= 0; i--) {
		xv_set(cntl_ui_olist, PANEL_LIST_DELETE, i, NULL);
	}

	list_item = 0;
	file = (char *)xv_get(cntl_ui_file_field, PANEL_VALUE);
	if (tt_file_objects_query(file,
                                     (Tt_filter_function)cntl_gather_specs,
                                   &list_item, NULL) != TT_OK) {
		xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER,
		       "Couldn't query objects for file", NULL);
		return 0;
	}

	return 1;
}

Within the tt_file_objects_query function, the application calls cntl_gather_specs, a filter function that inserts objects into a scrolling list. Example 12-2 illustrates how to insert the objid.

Example 12-2 Inserting the objid

/*
 * Function to insert the objid given into the scrolling lists of objects
 * for a file. Used inside tt_file_objects_query as it iterates through
 * all the ToolTalk objects in a file.
 */
Tt_filter_action
cntl_gather_specs(objid, list_count, acc)
     char *objid;
     void *list_count;
     void *acc;
{
	int *i = (int *)list_count;

	xv_set(cntl_ui_olist, PANEL_LIST_INSERT, *i,
	       PANEL_LIST_STRING, *i, objid,
	       NULL);

	*i = (*i + 1);

	/* continue processing */
	return TT_FILTER_CONTINUE;
}

Moving Object Specs

The objid contains a pointer to a particular file system where the spec information is stored. To keep spec information as available as the object described by the spec, the ToolTalk service stores the spec information on the same file system as the object. Therefore, if the object moves, the spec must move, too.

Use tt_spec_move to notify the ToolTalk service when an object moves from one file to another (for example, through a cut and paste operation).

• If a new objid is not required (because both the new and old files are in the same file system), the ToolTalk service returns TT_WRN_SAME_OBJID.

• If the object moved to another file system, the ToolTalk service returns a new objid for the object and leaves a forwarding pointer in the ToolTalk database from the old objid to the new one.

When your process sends a message to an out-of-date objid (that is, one with a forwarding pointer), tt_message_send returns a special status code, TT_WRN_STALE_OBJID, and replaces the object attribute in the message with a new objid that points to the same object in the new location.

Update any internal data structures that reference the object with the new objid.