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.

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

Destroying Object Specs

Use tt_spec_destroy to immediately destroy an object's spec.

Managing Object and File Information

Caution - Despite the efforts of the ToolTalk service and integrated applications, object references can still be broken if you remove, move, or rename files with standard operating system commands such as rm or mv. Broken references will result in undeliverable messages.

Managing Files that Contain Object Data

To keep the ToolTalk database that services the disk partition where a file that contains object data is stored up-to-date, use the ToolTalk functions to copy, move, or destroy the file. Table 12-3 lists the ToolTalk functions you use to manage files that contain object data.

Table 12-3 Functions to Copy, Move, or Remove Files that Contain Object Data

The return type for these functions is Tt_status.

Managing Files that Contain ToolTalk Information

The ToolTalk service provides ToolTalk-enhanced shell commands to copy, move, and remove ToolTalk object and file information. Table 12-4 lists the ToolTalk-enhanced shell commands that you and users of your application should use to copy, move, and remove files referenced in messages and files that contain objects.

Table 12-4 ToolTalk-Wrapped Shell Commands

An Example of Object-Oriented Messaging

You can run the edit_demo program for a demonstration of ToolTalk object-oriented messaging. This demo consists of two programs - cntl and edit. The cntl program uses the ToolTalk service to start an edit process with which to edit a specified file; the edit program allows you to create ToolTalk objects and associate the objects with text in the file. Once objects have been created and associated with text, you can use the cntl program to query the file for the objects and to send messages to the objects.

The following example code creates an object for its user. It has been divided into two parts. It creates the object spec, sets the otype, writes the spec to the ToolTalk database, and wraps the user's selection with C-style comments. The application also sends out a procedure-addressed notice after it creates the new object to update other applications who observe messages with the ToolTalk_EditDemo_new_object operation. If other applications are displaying a list of objects in a file managed by ToolTalk_EditDemo, they update their list after receiving this notice.

Example 12-3 Object Creation Part 1

/*
 * Make a ToolTalk spec out of the selected text in this textpane. Once
 * the spec is successfully created and written to a database, wrap the
 * text with C-style comments in order to delimit the object and send out
 * a notification that an object has been created in this file.
 */
Menu_item
edit_ui_make_object(item, event)
   Panel_item		item;
   Event		*event;
{
         int               mark = tt_mark();
	char		*objid;
	char		*file;
	char		*sel;
	Textsw_index		first, last;
	char		obj_start_text[100];
	char		obj_end_text[100];
	Tt_message		msg;

	if (! get_selection(edit_ui_xserver, edit_ui_textpane,
			  &sel, &first, &last)) {
		xv_set(edit_ui_base_window, FRAME_LEFT_FOOTER,
		       "First select some text", NULL);
		tt_release(mark);
		return item;
	}
	file = tt_default_file();

	if (file == (char *)0) {
		xv_set(edit_ui_base_window, FRAME_LEFT_FOOTER,
		       "Not editing any file", NULL);
		tt_release(mark);
		return item;
	}

Example 12-4 Object Creation Part 2

/*
	/* create a new spec */

	objid = tt_spec_create(tt_default_file());
	if (tt_pointer_error(objid) != TT_OK) {
		xv_set(edit_ui_base_window, FRAME_LEFT_FOOTER,
		       "Couldn't create object", NULL);
		tt_release(mark);
		return item;
	}

	/* set its otype */

	tt_spec_type_set(objid, "Sun_EditDemo_object");
	if (tt_spec_write(objid) != TT_OK) {
		xv_set(edit_ui_base_window, FRAME_LEFT_FOOTER,
		       "Couldn't write out object", NULL);
		tt_release(mark);
		return item;
	}

	/* wrap spec's contents (the selected text) with C-style */
	/* comments. */

	sprintf(obj_start_text," /* begin_object(%s) */", objid);
	sprintf(obj_end_text,"	/* end_object(%s) */", objid);
	(void)wrap_selection(edit_ui_xserver, edit_ui_textpane,
			   obj_start_text, obj_end_text);

	/* now send out a notification that we've added a new object */

	msg = tt_pnotice_create(TT_FILE_IN_SESSION,"Sun_EditDemo_new_object");
	tt_message_file_set(msg, file);
	tt_message_send(msg);

	tt_release(mark);
	return item;
}