Part III Optional Integration

Chapters 6 through 10 describe how to perform the following optional integration tasks:

• Integrate with the Workspace Manager to enable your application to determine the workspace location of each session at session start time

• Use the CDE custom widgets

• Invoke actions from within an application

• Access the data-typing database

• Access the Calendar API

Chapter 6, Integrating with the Workspace Manager, "Integrating with the Workspace Manager"




Chapter 7, Common Desktop Environment Motif Widgets, "Common Desktop Environment Motif Widgets"




Chapter 8, Invoking Actions from Applications, "Invoking Actions from Applications"




Chapter 9, Accessing the Data-Typing Database, "Accessing the Data-Typing Database"




Chapter 10, Integrating with Calendar, "Integrating with Calendar"

Chapter 6 Integrating with the Workspace Manager

The Workspace Manager provides the means for an application to manage its windows within the desktop's multiple workspace environment. An application can perform four major tasks by communicating with the Workspace Manager:

• Place the application's windows in one or more workspaces

• Identify the workspaces in which the application's windows are located

• Prevent the application's windows from moving to another workspace

• Monitor changes to the workspaces, such as when a user switches from one workspace to another

Normally, Session Manager will get your application main window into the right workspace without your intervention. However, if your application has multiple top-level windows, you should use the Workspace Manager API to figure out where your windows are and save this data as part of your session state.

See Chapter 4, Integrating with Session Manager for details on saving application-related information between sessions.

• "Communicating with the Workspace Manager"

• "Placing an Application Window in Workspaces"

• "Identifying Workspaces Containing the Application Windows"

• "Preventing Application Movement Among Workspaces"

• "Monitoring Workspace Changes"

Communicating with the Workspace Manager

An application communicates with the Workspace Manager by using functions provided by the desktop. These functions allow you to quickly and easily perform a variety of tasks associated with workspace management. The following is a list of these functions:

• DtWsmAddCurrentWorkspaceCallback()

• DtWsmAddWorkspaceFunctions ()

• DtWsmAddWorkspaceModifiedCallback ()

• DtWsmFreeWorkspaceInfo ()

• DtWsmGetCurrentBackdropWindows ()

• DtWsmGetCurrentWorkspace ()

• DtWsmGetWorkspaceInfo ()

• DtWsmGetWorkspaceList ()

• DtWsmGetWorkspacesOccupied ()

• DtWsmOccupyAllWorkspaces ()

• DtWsmRemoveWorkspaceCallback ()

• DtWsmRemoveWorkspaceFunctions ()

• DtWsmSetCurrentWorkspace ()

• DtWsmSetWorkspacesOccupied()

Segments of code from two demo programs (occupy.c and wsinfo.c) illustrate the use of these functions. Listings for occupy.c, wsinfo.c, and makefiles for several brands of workstations are in the directory /usr/dt/examples/dtwsm. See the applicable man page for more information on each function.

Placing an Application Window in Workspaces

An application can place its windows in any or all of the existing workspaces. DtWsmOccupyAllWorkspaces() places the windows in all currently defined workspaces, while DtWsmSetWorkspacesOccupied() places the windows in all workspaces named in a list that is passed to the function.

To Place an Application Window in All Workspaces

Use DtWsmOccupyAllWorkspaces().

In occupy.c, the callback allWsCB() for the Occupy All Workspaces push button calls this function.

DtWsmOccupyAllWorkspaces (XtDisplay(toplevel),
                           XtWindow(toplevel));

where:

• XtDisplay(toplevel) is the X display.

• XtWindow(toplevel) is the window to be placed in all workspaces.

See the DtWsmOccupyAllWorkspaces() man page for more information on this function.

To Place an Application Window in Specified Workspaces

Use DtWsmSetWorkspacesOccupied().

In occupy.c, the callback setCB() for the Set Occupancy push button calls this function.

DtWsmSetWorkSpacesOccupied XtDisplay(toplevel),
                              XtWindow(toplevel), paWsSet, numSet);

where:

• XtDisplay(toplevel) is the X display.

• XtWindow(toplevel) is the window to be placed in the workspaces.

• paWsSet is a pointer to a list of workspace names that have been converted to X atoms.

• numSet is the number of workspaces in the list.

See the DtWsmSetWorkspacesOccupied() man page for more information on this function.

Identifying Workspaces Containing the Application Windows

The function DtWsmGetWorkspacesOccupied() returns a list of the workspaces in which a specified application window resides. In occupy.c, the procedure ShowWorkspaceOccupancy() calls this function. Based on the results of this call, ShowWorkspaceOccupancy() changes the appearance of the toggle buttons that represent the workspaces. A check mark appears on every toggle button in whose workspace the application window resides.

To Identify Workspaces That Contain the Application Window

Use DtWsmGetWorkspacesOccupied().

rval = DtWsmGetWorkspacesOccupied(XtDisplay(toplevel)
            XtWindow(toplevel), &paWsIn, &numWsIn);

where:

• XtDisplay(toplevel) is the X display.

• XtWindow(toplevel) is the window to be searched for in the workspaces.

• paWsIn is the address of a pointer to a list of workspace names that have been converted to X atoms.

• numWsIn is the address of an integer into which the number of workspaces in the list is placed.

After this call, loops are set up to compare the list of workspaces (found in the procedure SetUpWorkspaceButtons() by DtWsmGetWorkspaceList()) with the list of workspaces in which the application window was found to reside. The toggle button resource XmNset is set to True for each toggle button that represents a workspace in which the application window resides.

Preventing Application Movement Among Workspaces

The function DtWsmRemoveWorkspaceFunctions() prevents an application from:

• Switching from one workspace to another

• Occupying all workspaces

• Being removed from the current workspace

DtWsmRemoveWorkspaceFunctions() does this by making that portion of the desktop Workspace Manager (dtwm) window menu inactive. The application should call DtWsmRemoveWorkspaceFunctions() before its top-level window is mapped because dtwm only checks workspace information at the time it manages the application's top-level window. If you need to call DtWsmRemoveWorkspaceFunctions() after the application's top-level window is managed, then you must first call the Xlib function XWithdrawWindow(), call DtWsmRemoveWorkspaceFunctions,() and then call XMapWindow() to remap the top-level window.

To Prevent Movement to Another Workspace

Use DtWsmRemoveWorkspaceFunctions().

DtWsmRemoveWorkspaceFunctions(XtDisplay(toplevel),
                               XtWindow(toplevel));

where:

• XtDisplay(toplevel) is the X display.

• XtWindow(toplevel) is the window for which workspace movement is to be prevented.

Monitoring Workspace Changes

You can monitor workspace changes by using either or both of the following functions:

• DtWsmAddCurrentWorkspaceCallback()

• DtWsmWorkspaceModifiedCallback()

DtWsmAddCurrentWorkspaceCallback() registers an application callback to be called whenever the Workspace Manager is switched to a new workspace. See the DtWsmAddCurrentWorkspaceCallback(3) man page for more information.

DtWsmWorkspaceModifiedCallback() registers an application callback to be called whenever a workspace is added, deleted, or changed. See the DtWsmWorkspaceModifiedCallback(3) man page for more information.

To Monitor Workspace Switching

Use DtWsmAddCurrentWorkspaceCallback().

In the demo program wsinfo.c, this function is called after the top-level widget is realized.

DtWsmAddCurrentWorkspaceCallback (toplevel, wschangecb, NULL);

where

• toplevel is the application's top level widget.

• wschangecb() is the name of the function to be called.

• NULL is the parameter for client data to be passed to the callback. In this case, no data is passed.

To Monitor Other Workspace Changes

Use DtWsmWorkspaceModifiedCallback().

DtWsmWorkspaceModifiedCallback toplevel, wschangecb, NULL);

where:

• toplevel is the application's top-level widget.

• wschangecb() is the name of the function to be called.

• NULL is the parameter for client data to be passed to the callback. In this case, no data is passed.

Chapter 7 Common Desktop Environment Motif Widgets

The Common Desktop Environment provides Motif 2.1 libraries (with bug fixes) and enhancements. In addition, the Common Desktop Environment provides four custom widgets you can use to provide certain OPEN LOOK^TM and Microsoft® Windows functionality. This chapter describes these Motif custom widgets.

• "Menu Button Widget (DtMenuButton)"

• "Text Editor Widget (DtEditor)"

The widget library, libDtWidget, contains four widgets that combine or enhance functionality of existing Motif 2.1 widgets:

• DtMenuButton provides menu-cascading functionality outside of the menu bar.

• DtEditor incorporates such single text editor functions as cut and paste.

• DtSpinBox combines a text field and arrow buttons in a control that can increment or decrement numeric or text values. It pre-dates the Motif widget XmSpinBox.

• DtComboBox combines a text field and a list box in a control that displays one of the valid choices for the text field. It pre-dates the Motif widget XmComboBox.

These widgets provide common functionality across all Common Desktop Environment applications. None of these widgets support subclassing.

The Custom Widgets library depends directly on the following libraries:

• Xm library for the Motif superclass support

• Xt library for creation and manipulation of widgets

• X11 Library for the base X Window System

• DtSvc for desktop support utilized by DtEditor

Menu Button Widget (DtMenuButton)

Use the DtMenuButton widget to provide menu-cascading functionality outside of a menu pane.

DtMenuButton widget is a command widget that complements the menu cascading functionality of an XmCascadeButton widget. As a complement to XmCascadeButton widget, it can only be instantiated outside a MenuBar, Pulldown, or Popup (use XmCascadeButton widget inside a MenuPane.)Figure 7-1 shows examples of a DtMenuButton widget.

Figure 7-1 Examples of menu button widget (DtMenuButton)

Library and Header Files

The DtMenuButton widget is in the libDtWidget library. The header file is Dt/MenuButton.h.

Demo Program

A demo containing an example of the DtMenuButton widget is in /usr/dt/examples/dtwidget/controls.c.

Convenience Functions

DtCreateMenuButton() is a convenience function that creates a Common Desktop Environment widget.

DtMenuButton widget is a subclass of XmLabel class. Visually, DtMenuButton widget has a label string and a menu glyph. The menu glyph always appears on the right end of the widget and, by default, is a downward pointing arrow.

DtMenuButton widget has an implicitly created submenu attached to it. The submenu is a pop-up menu and has this DtMenuButton widget as its parent. The name of the implicitly created submenu is obtained by prefixing submenu_ to the name of this DtMenuButton widget. You can obtain the widget ID of the submenu by setting an XtGetValues on DtNsubMenuId resource of this DtMenuButton widget. The implicitly created submenu must not be destroyed by the user of this widget.

The submenu can be popped up by pressing the menu post button (see XmNmenuPost resource of XmRowColumn) anywhere on the DtMenuButton widget or by pressing the Motif Cancel key (usually Escape).

Classes

DtMenuButtonWidget inherits behavior and resources from Core, XmPrimitive, and XmLabel classes.

The class pointer is dtMenuButtonWidgetClass.

The class name is DtMenuButtonWidget.

DtMenuButtonWidget does not support subclassing.

Resources

DtMenuButtonWidget provides the following resources. Table 7-1 shows the class, type, default, and access for these resources.

• DtNcascadingCallback specifies the list of callbacks that are called before the attached submenu is displayed.

• DtNcascadePixmap specifies the pixmap that is displayed as the menu glyph. If no pixmap is specified, a downward pointing arrow is displayed.

• DtNsubMenuId specifies the widget ID of the pop-up menu pane to be associated with this DtMenuButton widget. You must create the pop-up menu pane with this DtMenuButton as its parent. You cannot specify this resource when the widget is created because the submenu is automatically destroyed by this widget when the resource is set.

See the DtMenuButtonWidget(3X) man page for more information.

The codes in the access column show if you can:

• Set the resource at creation time (C)

• Set by using XtSetValues (S)

• Retrieve by using XtGetValues (G)

Callback Structures

The callback structure follows and is described in Table 7-2.

typedef struct {
 	int 	reason;
 	XEvent	*event;
} XmAnyCallbackStruct;

Example of DtMenuButton Widget

The following example shows how to create and use a DtMenuButton widget. You can find this code as part of the controls.c demo in the /usr/dt/examples/dtwidget directory.

/*
  * Example code for DtMenuButton
  */  

#include Dt/DtMenuButton.h  

/* MenuButton custom glyph */  

#define menu_glyph_width 16 
#define menu_glyph_height 16 
static unsigned char menu_glyph_bits[] = {
 	0xe0, 0x03, 0x98, 0x0f, 0x84, 0x1f, 0x82, 0x3f, 0x82, 0x3f, 0x81,
 	0x7f, 0x81, 0x7f, 0xff, 0x7f, 0xff, 0x40, 0xff, 0x40, 0xfe, 0x20, 0xfe,
 	0x20, 0xfc, 0x10, 0xf8, 0x0c, 0xe0, 0x03, 0x00, 0x00};

static void CreateMenuButtons(Widget parent) {
     Widget menuButton, submenu, titleLabel, button;
     Pixmap cascadePixmap;
     Pixel fg, bg;
     Cardinal depth;
     XmString labelString;
     Arg args[20];
     int i, n;

      /* Create title label */

     labelString = XmStringCreateLocalized("MenuButton Widget");
     n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
     titleLabel = XmCreateLabel(parent, "title", args, n);
     XtManageChild(titleLabel);
     XmStringFree(labelString);

     /*
      * Create a MenuButton.
      * Add push buttons to the built-in popup menu.
      */

     labelString = XmStringCreateLocalized("Action"); n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
     menuButton = DtCreateMenuButton(parent, "menuButton1", args, n);
     XtManageChild(menuButton);
     XmStringFree(labelString);
     XtVaGetValues(menuButton, DtNsubMenuId, &submenu, NULL);
     button = XmCreatePushButton(submenu, "Push", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Pull", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Turn", NULL, 0);
     XtManageChild(button);

     /*
      * Create a MenuButton.
      * Replace the built-in popup menu with a tear-off menu.
      * Add a custom pixmap in the colors of the MenuButton.
      */

     labelString = XmStringCreateLocalized("Movement");
     n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
  	  menuButton = DtCreateMenuButton(parent, "menuButton1", args, n);
     XtManageChild(menuButton);
     XmStringFree(labelString);

     /* Create a tear-off menu */

     n = 0;
     XtSetArg(args[0], XmNtearOffModel, XmTEAR_OFF_ENABLED); n++;
     submenu = XmCreatePopupMenu(menuButton, "submenu", args, n);
     button = XmCreatePushButton(submenu, "Run", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Jump", NULL, 0);
     XtManageChild(button);
     button = XmCreatePushButton(submenu, "Stop", NULL, 0);
     XtManageChild(button);

     XtVaSetValues(menuButton, DtNsubMenuId, submenu, NULL);

     /* Create a pixmap using the menu button's colors and depth */

     XtVaGetValues(menuButton,
 			XmNforeground, &fg,
 			XmNbackground, &bg,
 			XmNdepth, &depth,
 			NULL);

     cascadePixmap = XCreatePixmapFromBitmapData(XtDisplay
 	  (menuButton),DefaultRootWindow(XtDisplay
 	  (menuButton)),
 	  (char*)menu_glyph_bits,
 	  menu_glyph_width, menu_glyph_height,
     fg, bg, depth);
     XtVaSetValues(menuButton, DtNcascadePixmap, cascadePixmap,
 	  NULL); 
}

Text Editor Widget (DtEditor)

The Common Desktop Environment text editing system consists of two components:

• The text editor client, dtpad, which provides editing services through graphical, action, and ToolTalk interfaces.

• The editor widget, DtEditor(3), which provides a programmatic interface for the following editing services:

  • Cut and paste

  • Search and replace

  • Simple formatting

  • Spell checking (for 8-bit locales)

  • Undo previous edit

  • Enhanced I/O handling capabilities that support input and output of ASCII text, multibyte text, and buffers of data

  • Support for reading and writing files directly

Although the OSF/Motif text widget also provides a programmatic interface, applications that use the system-wide uniform editor should use the DtEditor(3) widget. The Common Desktop Environment Text Editor and Mailer use the editor widget. Use this widget in the following circumstances:

1. You want the functionality, such as spell checking, undo, and find/change, that is provided by the DtEditor(3) widget.

2. You do not want to write the code so that users may read and write data to and from a file.

3. Your program does not need to examine every character typed or every cursor movement made by a user.

This section describes the text editor widget, DtEditor(3).

The Editor Widget library provides support for creating and editing text files. It enables applications running in the desktop environment to have a consistent method of editing text data. The DtEditor(3) widget consists of a scrolled edit window for text, an optional status line, and dialogs for finding and changing text, spell checking, and specifying formatting options. The text editor widget includes a set of convenience functions for programmatically controlling the widget.

Library and Header Files

The DtEditor widget is in the libDtWidget library. The header file is Dt/Editor.h.

Demo Program

A demo containing an example of the DtEditor widget is in /usr/dt/examples/dtwidget/editor.c.

Classes

Widget subclassing is not supported for the DtEditor widget class.

DtEditor inherits behavior and resources from Core, Composite, Constraints, XmManager, and XmForm classes.

The class name for the editor widget is DtEditorWidget.

The class pointer is dtEditorWidgetClass.

Convenience Functions

The DtEditor convenience functions are described in the following tables.

Life Cycle Functions

The DtEditor life cycle functions are described in Table 7-3.

Input/Output Functions

The DtEditor input/output functions are described in Table 7-4.

Selection Functions

The DtEditor selection functions are described in Table 7-5.

Format Functions

The DtEditor format functions are described inTable 7-6.

Find and Change Functions

The DtEditor find and change functions are described in Table 7-7.

Auxiliary Functions

The DtEditor auxiliary functions are described in Table 7-8.

Resources

The DtEditor widget provides the following set of resources.

• DtNautoShowCursorPosition ensures that the text visible in the scrolled edit window contains the insert cursor when set to True. If the insert cursor changes, the contents of the editor may scroll to bring the insertion point into the window.

• DtNblinkRate specifies the blink rate of the text cursor in milliseconds. The time it takes to blink the insertion cursor on and off is twice the blink rate. When the blink rate is set to zero, the cursor does not blink. The value must not be negative.

• DtNbuttonFontList specifies the font list used for the buttons that are displayed in the dialog boxes of DtEditor.

• DtNcolumns specifies the initial width of the editor as an integer number of characters. The value must be greater than zero.

• DtNcursorPosition specifies the location of the current insert cursor in the editor where the current insert cursor is placed. Position is determined by the number of characters from the beginning of the text. The first character position is 0.

• DtNcursorPositionVisible marks the insert cursor position by a blinking text cursor when the Boolean value is True.

• DtNdialogTitle specifies the title for all dialogs displayed by DtEditor. These include the dialogs for word search and replace, misspelled words, and format settings.

• DtNeditable indicates that the user can edit the data when set to True. Prohibits the user from editing data when set to False.

• DtNlabelFontList specifies the font list used for DtEditor labels (the labels are displayed in the status line and DtEditor dialog boxes).

• DtNoverstrike when set to False, characters typed into the editor widget inserts at the position of the cursor (the default). When set to True, characters typed into the editor widget replace the characters that directly follow the insertion cursor. When the end of the line is reached, characters are appended to the end of the line. If the status line is visible, the DtNoverstrikeIndicatorLabel is displayed in the status line whenever DtNoverstrike is True.

• DtNrows specifies the initial height of the editor measured in character heights. The value must be greater than zero.

• DtNscrollHorizontal adds a scroll bar that enables the user to scroll horizontally through text when the Boolean value is True.

• DtNscrollLeftSide puts a vertical scroll bar on the left side of the scrolled edit window when the Boolean value is True.

• DtNshowStatusLine displays a status line below the text window when set to True. The status line contains a field that displays the current line number of the insert cursor, total number of lines in the document, and whether the editor is in overstrike mode. Users can type a line number in the line number display to go directly to that line.

The status line also includes a Motif XmTextField(3X) widget for displaying messages supplied by an application. This field is a convenient place for an application to display status and feedback about the document being edited. The ID of the text field is retrieved using DtEditorGetMessageTextFieldID(3). A message is displayed by setting the XmNvalue or XmNvalueWcs resource of this widget. If the text field is not needed, you can unmanage it by calling XtUnmanageWidget(3X) with its ID.

• DtNspellFilter specifies the filter used to identify spelling errors. The function DtEditorInvokeSpellDialog(3) filters the contents of an editor through the filter specified by DtNspellFilter. The filter specified should accept a file name and produce a list of misspelled and unrecognized words in this file on stdout. The default filter is spell(1).

• DtNtextBackground specifies the background for the edit window.

• DtNtextDeselectCallback specifies a function called whenever no text is selected within the edit area. The reason sent by the callback is DtEDITOR_TEXT_DESELECT.

• DtNtextFontList specifies the font list used for the DtEditor edit window and its text fields. The text fields are displayed in the status line and DtEditor dialog boxes.

• DtNtextForeground specifies the foreground for the edit window.

• DtNtextSelectCallback specifies a function called whenever text is selected within the edit area. The reason sent by the callback is DtEDITOR_TEXT_SELECT.

• DtNtextTranslations specifies translations that are added to the edit window. Translations specified with this resource override any duplicate translations defined for the edit window. See the DtEditor(3) man page for a list of translations provided by DtEditor.

• DtNtopCharacter displays the line that contains the position of text at the top of the scrolled edit window. The line is displayed at the top of the widget without shifting the text left or right. Position is determined by the number of characters from the beginning of the text. The first character position is zero.

• XGetValues(3X) for DtNtopCharacter returns the position of the first character in the line that is displayed at the top of the widget.

• DtNwordWrap breaks lines at word breaks with soft carriage returns when they reach the right edge of the window. Note that word wrap affects only the visual appearance of the contents of an editor widget. The line breaks (soft carriage returns) are not physically inserted into the text. The editor does support substituting hard carriage returns when the contents of the widget are retrieved or saved to a file. See the DtEditorGetContents(3) and DtEditorSaveContentsToFile(3) man pages for more information.

Table 7-9 lists the class, type, default, and access for each resource. You can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or class in an .Xdefaults file, remove the DtN or DtC prefix and use the remaining letters. To specify one of the defined values for a resource in an .Xdefaults file, remove the Dt prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words).

The codes in the access column show if you can:

• Set the resource at creation time (C)

• Set by using XtSetValues (S)

• Retrieve by using XtGetValues (G)

See the DtEditor(3) man page for more information.

Inherited Resources

DtEditor inherits behavior and resources from the following superclasses:

• XmForm

• XmManager

• Composite

• Core

Refer to the appropriate man page for more information.

Localization Resources

The following list describes a set of widget resources that are designed for localization of the DtEditor widget and its dialog boxes. Default values for these resources depend on the locale.

• DtNcenterToggleLabel specifies the label for the center alignment toggle button in the Format Settings dialog box. The default value in the C locale is Center.

• DtNchangeAllButtonLabel specifies the label for the button in the Find/Change dialog box that changes all occurrences of the Find string in the document. The default value in the C locale is Change All.

• DtNchangeButtonLabel specifies the label for the button in the Find/Change dialog box that changes the next occurrence of the find string in the document. The default value in the C locale is Change.

• DtNchangeFieldLabel specifies the label for the field in the Find/Change dialog box where the user specifies the replacement string. The default value in the C locale is Change To.

• DtNcurrentLineLabel specifies the label for the current line number field in the status line. The default value in the C locale is Line.

• DtNfindButtonLabel specifies the label for the button in the Find/Change dialog box that finds the next occurrence of the find string in the document. The default value in the C locale is Find.

• DtNfindChangeDialogTitle specifies the title for the Find/Change dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Find/Change.

• DtNfindFieldLabel specifies the label for the field in the Find/Change dialog box where the user specifies the search string. The default value in the C locale is Find.

• DtNformatAllButtonLabel specifies the label for the button in the Format Settings dialog box that formats the complete document. The default value in the C locale is All.

• DtNformatParagraphButtonLabel specifies the label for the button in the Format Settings dialog box that formats the paragraph containing the insertion cursor. The default value in the C locale is Paragraph.

• DtNformatSettingsDialogTitle specifies the title for the Format Settings dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Format Settings.

• DtNinformationDialogTitle specifies the title for the Information dialog box that is used to present feedback and general information to the user. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Information.

• DtNjustifyToggleLabel specifies the label for the justify alignment toggle button in the Format Settings dialog box. The default value in the C locale is Justify.

• DtNleftAlignToggleLabel specifies the label for the left alignment toggle button in the Format Settings dialog box. The default value in the C locale is Left Align.

• DtNleftMarginFieldLabel specifies the label for the left margin value field in the Format Settings dialog box. The default value in the C locale is Left Margin.

• DtNmisspelledListLabel specifies the label for the list of unrecognized and misspelled words in the Spell dialog box. The default value in the C locale is Misspelled Words.

• DtNoverstrikeLabel specifies the label in the status line that shows that the editor is in overstrike mode. The default value in the C locale is Overstrike.

• DtNrightAlignToggleLabel specifies the label for the right alignment toggle button in the Format Settings dialog box. The default value in the C locale is Right Align.

• DtNrightMarginFieldLabel specifies the label for the right margin value field in the Format Settings dialog box. The default value in the C locale is Right Margin.

• DtNspellDialogTitle specifies the title for the Format Settings dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Spell.

• DtNtotalLineCountLabel specifies the label for the display as part of the status line that shows the total number of lines in the document. The default value in the C locale is Total.

Table 7-10 lists the class, type, default, and access for each of the localization resources. The codes in the access column show if you can:

• Set the resource at creation time (C)

• Set by using XtSetValues (S)

• Retrieve by using XtGetValues (G)

See the DtEditor(3) man page for more information.

Callback Functions

The DtEditor widget supports three callback functions:

• DtEditorNHelpCallback

• DtNtextSelectCallback

• DtNtextDeselectCallback

If you want to present help information about the editor widget and its dialog boxes, set the XmNhelpCallback resource and use the reason field passed as part of DtEditorHelpCallbackStruct to set the contents of the Help dialog box. A pointer to the following structure is passed to XmNHelpCallback. The callback structure and is described in Table 7-11.

typedef struct {
		int     reason;
 	XEvent   *event;
} DtEditorHelpCallbackStruct;

Use the DtNtextSelectCallback and DtNtextDeselectCallback resources when you want to enable and disable menu items and commands depending on whether text is selected. DtNtextSelectCallback specifies a function that is called whenever some text is selected in the edit window. DtNtextDeselectCallback specifies a function that is called whenever no text is selected within the edit window. The reasons sent by the callbacks are DtEDITOR_TEXT_SELECT and DtEDITOR_TEXT_DESELECT.

Chapter 8 Invoking Actions from Applications

If your application manages an extensible collection of data types, there is a strong likelihood that it should be directly involved with action invocation. This chapter explains how you can invoke an action from an application. Included is an example program that shows you how to invoke an action.

For more information on actions and how you create them, see Chapter 9, Accessing the Data-Typing Database, in this manual, and the following chapters in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide.

• "Introduction to Actions and Data Types" in Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

• "Creating Actions and Data Types Using Create Action" in Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

• "Creating Actions Manually" in Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

• "Creating Data Types Manually" in Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

• "Mechanisms for Invoking Actions from an Application"

• "Types of Actions"

• "Action Invocation API"

• "Related Information"

• "actions.c Example Program"

• "Listing for actions.c"

Mechanisms for Invoking Actions from an Application

The action invocation API exported by the Desktop Services library is one mechanism available to your application to cause another application to be invoked or to perform an operation. Other mechanisms include:

• The fork/exec system calls

• ToolTalk messages

Each of these mechanisms has benefits and limitations, so you must evaluate your specific situation to determine which is most appropriate.

The advantages of using the action invocation API include:

• Actions can encapsulate both traditional command-line applications (that is, COMMAND actions) and ToolTalk applications (that is, TT_MSG actions). The application that invokes the action does not need to know whether a command is forked or a message is sent.

• Actions are polymorphic and are integrated with the desktop's data-typing mechanisms. This means that an action, such as Open or Print, may have different behavior depending on the type of argument that is supplied, but the behavior differences are transparent to the application that invokes the action.

• Actions provide a great deal of configurability for the application developer, system integrator, system administrator, and end user. Any one of these people can edit the action database to modify the definition of how an action is to be performed.

• Actions work well in distributed environments. If an application uses fork/exec to directly invoke another application, then both applications must be available and able to run on the same system. By contrast, the action invocation API uses information in the action database to determine on which system a COMMAND action should be invoked.

• Actions enable your application to behave consistently with the behavior of the desktop. This is because the desktop's components interact by using actions when manipulating the user's data files.

The disadvantage of using the action invocation API is that it is only an invocation mechanism that has limited return value capabilities and has no capabilities for a dialog with the invoked action handler. If these features are required, fork/exec/pipes can be used. However, within CDE, ToolTalk is the preferred cross process communications mechanism due to its generalized client/server paradigm.

Returning to invocation, suppose your application manages data files in several different formats (text and graphics) and needs to provide a way for the user to edit and display these files. To implement this feature without using actions, you would probably use one of the following mechanisms:

• Use fork/exec to start the appropriate editor and invent some mechanism (for example, environment variables) for the user to specify the names of the editors. The limitations of this approach include the following:

  • You must write complex code that uses system calls to invoke subprocesses and monitors the resulting signals.

  • The editors must either be available on the same system as your application or the system administrator must provide a complex configuration using facilities such as rsh.

  • System administrators and users must learn and manage your application's unique configuration model.

• Use ToolTalk messages to request that operations, such as Edit and Display, be performed on the data. The limitation of this approach is that ToolTalk-based editors must be available for all of your types of data.

To implement this feature using actions, you only have to invoke the Open action on the buffer or on the data file. The action invocation API will use the action database to determine the appropriate message to send or command to invoke as well as handle all details, such as creating and cleaning up temporary files and catching necessary signals.

Types of Actions

The action application program interface (API) works with any type of action. Types of actions in the desktop include:

See "Introduction to Actions and Data Types" in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide for more information.

Action Invocation API

The action invocation API is exported from the Desktop Services library and provides functions to accomplish a number of tasks, such as:

• Initializing and loading the database of action and data-type definitions. The database must be loaded before an action can be run.

• Querying the database. There are functions to determine whether a specified action or its associated icon image, label, or description exists.

• Invoking an action. The application can pass file or buffer arguments to the action.

• Registering a callback to receive action status and return arguments.

Related Information

For detailed information about action commands, functions, and data formats, see the following man pages:

• dtaction(1)

• dtactionfile(4)

• DtActionCallbackProc(3)

• DtActionDescription(3)

• DtActionExists(3)

• DtActionIcon(3)

• DtActionInvoke(3)

• DtActionLabel(3)

• DtActionQuit(3)

• DtActionQuitType(3)

• DtActionStUpCb(3)

• dtexec(1)

actions.c Example Program

This section describes a simple example program, actions.c. A complete listing of actions.c is at the end of this chapter.

Loading the Database of Actions and Data Types

Before your application can invoke an action, it must initialize the Desktop Services library (which contains the action invocation API) and load the database of action and data-type definitions.

To Initialize the Desktop Services Library

1. Use the DtInitialize() function to initialize the Desktop Services Library.

   DtInitialize(*display,widget,*name,*tool_class)

   DtInitialize() uses the default Intrinsic XtAppContext. The API provides an additional function, DtAppInitialize() to use when your application must specify an app_context:

   DtAppInitialize(app_context,*display,widget,*name, tool_class)

DtInitialize() Example

The following code segment shows how the example program actions.c uses DtInitialize().

To Load the Actions and Data-Typing Database

    if (DtInitialize(XtDisplay(shell), shell,

argv[0],ApplicationClass)==False) {
    /* DtInitialize() has already logged an appropriate error msg */
            exit(-1);
    }

Use the DtDbLoad() function to load the actions and data-typing database.

DtDbLoad(void)

DtDbLoad() reads in the action and data-typing database. This function determines the set of directories that are to be searched for database files (the database search path) and loads the *.dt files found into the database. The directory search path is based on the value of the DTDATABASESEARCHPATH environment variable and internal defaults.

To Request Notification of Reload Events

If you use DtDbLoad() in a long-lived application, it must dynamically reload the database whenever it is modified.

1. Use the DtDbReloadNotify()function to request notification of reload events.

   /* Notice changes to the database without needing to restart
   	 application */
   
     	DtDbReloadNotify(DbReloadCallbackProc, callback_proc,
   	 	XTPointer, client_data);

   Supply a callback that:

   • Destroys cached database information held by the application

   • Calls the DtDbLoad() function again

Callback_proc cleans up any cached database information your application is holding and then invokes DtDbLoad(). Client_data may be used to pass additional client information to the callback routine.

Checking the Actions Database

Your application accesses the database if it needs to display the icon or label for an action. Also before invoking an action, your application can check that it exists. An action is identified in the database by the action name:

ACTION action_name
{
  ... 
}

For example, the action definition for the Calculator looks like this:

ACTION Dtcalc
{
      LABEL        Calculator
      ICON          Dtcalc
      ARG_COUNT          0 
      TYPE                 COMMAND
      WINDOW_TYPE           NO_STDIO
      EXEC_STRING           /usr/dt/bin/dtcalc
      DESCRIPTION           The Calculator (Dtcalc) action runs the \
                              desktop Calculator application. 
}

The action name for the Calculator action is Dtcalc.

When an executable file has a file name that matches an action name in the existing database, that file is an action file--a representation for the underlying action. The information about the icon and label for that file are stored in the database.

To Determine Whether a Specified Action Definition Exists

Use the DtActionExists() function to determine whether a specified action definition exists.

DtActionExists(*name)

DtActionExists() checks whether the specified name corresponds to the name of an action in the database. The function returns True if name corresponds to an action name, or False if no action with that name is found.

To Obtain the Icon Image Information for a Specified Action

Use the DtActionIcon() function to obtain the icon image information.

DtActionIcon(char *action_name)

An action definition specifies the icon image used to represent the action in the definition's ICON field:

ACTION action_name
{
     ICON icon_image_base_name  
     ... 
}

DtActionIcon() returns a character string containing the value of the icon image field. If the action definition does not contain an icon field, the function returns the value of the default action icon image, Dtactn.

You then need to determine the location of the icon, and the size you want to use. Icons can exist in four sizes and are available in bitmap or pixmap form. For example, you can find the base name of the icon file from the action definition for the Calculator. You then use the base name coupled with the information given in Table 8-1 and knowledge of the location of all the icons to find the specific icon file you want.

The icon name for the calculator action is Dtcalc, but that is not the entire file name. Icon file names are based on the size of the icon. Table 8-1 shows the sizes and file-naming conventions for the desktop icons.

See "Creating Icons for the Desktop" in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide for more information about the desktop icon files.

For bitmaps, there is an additional file that is used as a mask, and its extension ends with _m.bm. Thus, there can be a total of three files for each size icon. Here are the icon files for the calculator:

Dtcalc.t.bm  
Dtcalc.t.pm
Dtcalc.t_m.bm  
Dtcalc.m.bm  
Dtcalc.m.pm  
Dtcalc.m_m.bm  
Dtcalc.l.bm 
Dtcalc.l.pm  
Dtcalc.l_m.bm

There are no small icons (Dtcalc.s.bm, Dtcalc.s.pm, Dtcalc.s_m.bm) for the Calculator.

DtActionIcon() returns only a base name; for the Calculator it is Dtcalc. You must choose the type (pixmap or bitmap) and size (tiny, small, medium, or large) and append the applicable extension to the base name. In addition, you must know where the file resides.

To Get the Localized Label for an Action

Use the DtActionLabel() function to get the localized label for an action.

char *DtActionLabel(char *actionName)

An action definition may include a label. The label is defined using the label_text field:

ACTION action_name {

   LABEL label_text
   ...
}

This label is used in graphical components (such as File Manager and the Application Manager) to label the action's icon. If an action definition does not include a label_text field, the action_name is used.

The value of label_text string should be used by all interface components to identify the action to the end user.

The DtActionLabel() function returns the value of the label_text field in the action definition of the action named actionName. If the label_text field does not exist, the function returns the actionName.

Invoking Actions

After your application has initialized the Desktop Services Library it can then invoke an action.

To Invoke an Action

Use theDtActionInvoke function to invoke an action.

DtActionInvoke (widget, action, args, argCount, termOpts, execHost,, 
		contexDir, useIndicator,statusUpdateCb, client_data)

DtActionInvoke() searches the action database for an entry that matches the specified action name, and accepts arguments of the class, type, and count provided. Remember that your application must initialize and load the database before invoking an action.

Listing for actions.c

/*
  * (c) Copyright 1993, 1994 Hewlett-Packard Company
  * (c) Copyright 1993, 1994 International Business Machines Corp.
  * (c) Copyright 1993, 1994 Sun Microsystems, Inc.
  * (c) Copyright 1993, 1994 Novell, Inc.
  */  

#include <Xm/XmAll.h> 
#include <Dt/Dt.h> 
#include <Dt/Action.h>  

#define ApplicationClass "Dtaction" 
 
static Widget shell; 
static XtAppContext appContext; 
static Widget actionText; 
static Widget fileText;  

static void CreateWidgets(Widget); 
static void InvokeActionCb(Widget, XtPointer, XtPointer); 
static void InvokeAction(char*, char*); 
static void DbReloadProc(XtPointer);  

void main(int argc, char **argv) 
{
     Arg args[20];
     int n=0;
     int numArgs = 0;

      shell = XtAppInitialize(&appContext , ApplicationClass, NULL, 0,
 								&argc, argv, NULL, args, n);

      CreateWidgets(shell);

   	if (DtInitialize(XtDisplay(shell), shell, argv[0],
 		ApplicationClass)==False) {
         /* DtInitialize() has already logged an appropriate error msg */
         exit(-1);
     }

     /* Load the filetype/action databases */
     DtDbLoad();
 /* Notice changes to the database without needing to restart application
 */
     DtDbReloadNotify(DbReloadProc, NULL);
     XtRealizeWidget(shell);
     XmProcessTraversal(actionText, XmTRAVERSE_CURRENT);

     XtAppMainLoop(appContext); 
}  

static void CreateWidgets(Widget shell) 
{
     Widget messageBox, workArea, w;
     Arg args[20];
     int n;
     XmString labelString;
      labelString = XmStringCreateLocalized("Invoke");
      n = 0;
     XtSetArg(args[n], XmNdialogType, XmDIALOG_TEMPLATE); n++;
     XtSetArg(args[n], XmNokLabelString, labelString); n++;
     messageBox = XmCreateMessageBox(shell, "messageBox", args, n);
     XtManageChild(messageBox);
     XmStringFree(labelString);
     XtAddCallback(messageBox, XmNokCallback, InvokeActionCb, NULL);

     n = 0;
     XtSetArg(args[n], XmNorientation, XmVERTICAL); n++;
     XtSetArg(args[n], XmNpacking, XmPACK_COLUMN); n++;
     XtSetArg(args[n], XmNnumColumns, 2); n++;
     XtSetArg(args[n], XmNentryAlignment, XmALIGNMENT_END); n++;
     workArea = XmCreateWorkArea(messageBox, "workArea", args, n);
     XtManageChild(workArea);

     labelString = XmStringCreateLocalized("Invoke Action:");
     n = 0;
     XtSetArg(args[n], XmNlabelString, labelString); n++;
     w = XmCreateLabel(workArea, "actionLabel", args, n);
     XtManageChild(w);
     XmStringFree(labelString);

     labelString = XmStringCreateLocalized("On File:");
     n = 0;     XtSetArg(args[n], XmNlabelString, labelString); n++;
     w = XmCreateLabel(workArea, "fileLabel", args, n);
     XtManageChild(w);
     XmStringFree(labelString);

     n = 0;
     XtSetArg(args[n], XmNcolumns, 12); n++;
     actionText = XmCreateTextField(workArea, "actionText", args, n);
     XtManageChild(actionText);

     n = 0;
     XtSetArg(args[n], XmNcolumns, 12); n++;
     fileText = XmCreateTextField(workArea, "fileText", args, n);
     XtManageChild(fileText); 
}  

static void DbReloadProc(XtPointer cd) 
{
     /* Pick up any dynamic changes to the database files */
     DtDbLoad(); 
}  

static void InvokeActionCb(Widget w, XtPointer cd, XtPointer cb) 
{
     char *action;
     char *file;

     action = XmTextFieldGetString(actionText);
     if (action == NULL) return;
     if (strlen(action) == 0) {
         XtFree(action);
         return;
     }

     file = XmTextFieldGetString(fileText);

     InvokeAction(action, file);

     XtFree(action);
     XtFree(file); 

     XmTextFieldSetString(actionText, "");
     XmTextFieldSetString(fileText, "");
     XmProcessTraversal(actionText, XmTRAVERSE_CURRENT); 
}  

static void InvokeAction(char *action, char *file) 
{
     DtActionArg *ap = NULL;

int nap = 0;
     DtActionInvocationID actionId;

      /* If a file was specified, build the file argument list */  

printf("%s(%s)\n",action,file);
     if (file != NULL && strlen(file) != 0) {
         ap = (DtActionArg*) XtCalloc(1, sizeof(DtActionArg));
         ap[0].argClass = DtACTION_FILE;
         ap[0].u.file.name = file;
         nap = 1;
     }

     /* Invoke the specified action */

  actionId = DtActionInvoke(shell,action,ap,nap,
              NULL,NULL,NULL,True,NULL,NULL); 

}

Chapter 9 Accessing the Data-Typing Database

This chapter describes the data-typing functions and how to use the data-typing database.

• "Summary"

• "Data Criteria and Data Attributes"

• "Data-Typing Functions"

• "Registering Objects as Drop Zones"

• "Example of Using 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 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:

• A database that stores data criteria and data attributes

• A collection of routines that query the database

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

• CONTENT

• DATA_ATTRIBUTES_NAME

• LINK_NAME

• LINK_PATH

• MODE

• NAME_PATTERN

• PATH_PATTERN

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

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

• ACTIONS

• COPY_TO_ACTION

• DESCRIPTION

• ICON

• INSTANCE_ICON

• IS_EXECUTABLE

• IS_TEXT

• LINK_TO_ACTION

• MEDIA

• MIME_TYPE

• MOVE_TO_ACTION

• NAME_TEMPLATE

• PROPERTIES

• X400_TYPE

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

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.

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.

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.

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);     
}

Chapter 10 Integrating with Calendar

The Calendar application program interface (API) provides a programmatic way to access and manage calendar data in a networked environment. The API supports inserting, deleting, and modifying of entries as well as browse and find capabilities. It also supports calendar administration functions.

The Calendar API is an implementation of the X.400 Application Programming Interface Association's (XAPIA) Calendaring and Scheduling API (CSA API). CSA API defines a set of high-level functions so that applications that are calendar enabled can access the varied features of the calendaring and scheduling service. For more information about the latest XAPIA Specification, contact the X.400 API Association, 800 El Camino Real, Mountain View, California 94043.

This chapter describes the Calendar API in these sections:

• "Library and Header Files"

• "Demo Program"

• "Using the Calendar API"

• "Overview of the CSA API"

• "Functional Architecture"

• "Data Structures"

• "Calendar Attributes"

• "Entry Attributes"

• "General Information About Functions"

• "Administration Functions"

• "Calendar Management Functions"

• "Entry Management Functions"

• "Code Examples"

Library and Header Files

To use the Calendar API, you need to link with the libcsa library. The header file is csa/csa.h.

Demo Program

A demo program containing an example of how to use the Calendar API is in /usr/dt/examples/dtcalendar.

Using the Calendar API

How to Integrate with Calendar

The Calendar API provides a way to access and manage calendar data in a networked environment.

1. Include csa/csa.h in your application.

2. Use the calendar API to incorporate the calendar operations you want in your application.

3. Link with libcsa.

Overview of the CSA API

The CSA interface enables a common interface to a calendaring and scheduling service. For each CSA implementation, the view and capabilities presented by CSA must be mapped to the view and capabilities of the underlying calendaring service. The interface is designed to be independent of the actual calendaring and scheduling implementation. The interface is also designed to be independent of the operating system and underlying hardware used by the calendaring service.

The number of function calls provided is minimal. A single set of functions manage multiple types of calendar entries.

C Naming Conventions

The identifier for an element of the C interface is derived from the generic name of the element and its associated data type, as specified in Table 10-1 . The generic name is prefixed with the character string in the second column of the table; alphabetic characters are converted to the case in the third column.

Elements with the prefix CSAP (any case) are reserved for internal proprietary use by implementors of the CSA service. They are not intended for direct use by programs written using the CSA interface.

The prefixes CSA_XS_, CSA_X_ (in either uppercase or lowercase), and csa_x are reserved for extensions of the interface by vendors or groups. The specification defines these interface extensions as extensions to the base set of functions.

For constant data values, an additional string is usually appended to CSA_ to indicate the data structure or function for the constant data value.

Functional Architecture

This section describes the functional architecture of services supporting the CSA API. It provides an abstract implementation model, an abstract data model, and a functional overview.

Implementation Model

The abstract implementation model is provided as a reference aid to help you understand the scope of the CSA API.

The CSA interface is defined between a calendar-enabled application and a calendaring service. All functions in this interface are designed to be independent of the calendaring service; however, the API does allow protocol-specific extensions to the common functions to be invoked through the use of extensions. See "Extensions" for more information. The relationship of the CSA interface to a calendar-enabled application and the calendar service is shown in Figure 10-1.

Figure 10-1 Positioning of the Calendaring and Scheduling API

The model of the CSA interface can be divided into three components: administration, calendar management, and entry management. These components are shown in Figure 10-2.

Figure 10-2 Components of the Calendaring and Scheduling API

Access to the calendaring service is established through a calendaring session. The session provides for a valid connection to the calendaring service and assists in ensuring the integrity of the calendaring information maintained by the service. A calendar-enabled application logs on to an individual calendar within the calendaring service to establish a valid session or connection. The session is terminated by the calendar-enabled application logging off from the calendar.

The calendaring service maintains one or more calendars. The calendar service provides some level of administration support for these calendars. A calendar-enabled application might access a list of the calendars maintained by a particular calendar service. In addition, the calendar service might provide support for archive and restore of calendar information into some implementation-specific, persistent format. Where a calendar service provides support for maintaining more than one calendar, support functions are defined for creating and deleting calendars. In addition, functions are provided to support administering the characteristics of the calendar.

The majority of the functions within the CSA interface manage individual calendar entries. Calendar entries may be either events, to dos, or memos. Entries can be added, deleted, updated, and read from a particular calendar. A calendar-enabled application can also add reminders to calendar entries.

Data Model

The CSA interface is an access method to a conceptual back-end store of calendaring information that is maintained by a calendaring service. A common data model is helpful in visualizing the components of the calendaring information maintained by a calendaring service.

Calendar Entities

The data model is based on the concept of a calendar entity. The calendar is represented by a named collection of administrative calendar attributes and calendar entries. A calendar is owned by an individual user. The user could represent a person, a group of people, or a resource.

The calendar attributes are a set of named values that may represent common, implementation-specific, or application-specific administrative characteristics about the calendar. For example, time zone, name, owner, and access rights to the calendar can be specified in individual calendar attributes.

The calendar entries are the primary components of a calendar. The three classes of calendar entries follow:

• Events

• To Dos

• Memos

Calendar entries are represented by a uniquely named collection of entry attributes. The entry attributes are a set of named values that represent common, implementation-specific, or application-specific characteristics of the calendar entry. For example, an event might contain a start and end date and time, a description, and a subtype. A to do might contain the date it was created, the due date, a priority, and a status. A memo might contain the date it was created and a text content or description.

The calendar attributes and entry attributes consist of a name, type, and value tuple. Common attributes defined by the specification can be extended. Implementations can define implementation-specific attributes. In addition, some implementations may provide the capability for applications to define application-specific attributes. The CDE implementation supports application-defined attributes.

Access Rights

The accessibility of a calendar to an individual user can be controlled by the access rights given that user. Access rights are paired with a calendar user. CSA allows a user to be an individual, group, or resource. The CDE implementation only supports individual users. The access rights are maintained in an access list. The access list is a particular calendar attribute. The access rights are individually controlled and can be accumulated to define a range of accessibility of a user to a calendar and its entries. The access rights can also be specified in terms of the following access roles:

• The owner of a calendar

• The organizer of a particular entry within the calendar

• The sponsor of a particular entry within the calendar

The owner role enables the user to do anything to the calendar or calendar entries that the owner of the calendar can do, including deleting the calendar; viewing, inserting, and changing calendar attributes; adding and deleting calendar entries; and viewing, inserting, and changing entry attributes.

The organizer role enables the user to delete the entry or view and change entry attributes of those calendar entries for which the user is specified as the organizer. The organizer defaults to the calendar user who created the entry.

The sponsor role enables the user to delete the entry or view and change entry attributes for those calendar entries for which the user is specified as the sponsor. The sponsor is the calendar user who effectively owns the calendar entry.

In addition to these roles, an access right can be set to limit access to free time searches; view, insert, or change calendar attributes; or view, insert or change entries, depending on whether they are classified as public, confidential, or private. The entry classification acts as a secondary filter on accessibility.

Functional Overview

The CSA interface supports three principle types of tasks:

• Administration

• Calendar management

• Entry management

Administration

Most of the CSA function calls occur within a calendar session. The calendar session is a logical connection between the calendar-enabled application and a particular calendar maintained by the calendaring service. A session is established with a call to the csa_logon() function and terminated with a call to the csa_logoff() function. The context of the session is represented by a session handle. This handle provides a token in each of the CSA functions to distinguish one calendar session from another. The csa_logon() function also authenticates the user to the calendaring service and sets session attributes. Currently, there is no support for sharing calendar sessions among applications.

The csa_list_calendars() function is used to list the names of the calendars managed by a particular calendar service.

The csa_query_configuration() function is used to list information about the current calendar service configuration. This information can include the character set, line terminator characters for text strings, default service name, default authorization user identifier for the specified calendar service, an indicator of whether a password is needed to authenticate the user identifier, an indicator of whether the common extensions for user interface dialogs is supported, and the CSA specification supported by the implementation.

The CSA implementation provides support for managing the memory for calendar objects and attributes that are returned by the service. The csa_free() function is used to free up this memory after it is no longer needed. It is the responsibility of the application to free up the memory allocated and managed by the calendar service.

Calendar Management

The CSA interface provides several calendar management functions. The CDE implementation supports multiple calendars per calendar service; the calendar-enabled application can add or delete calendars. The csa_delete_calendar() function is used to delete calendars. The csa_add_calendar() function is used to add new calendars to the service.

The application can also list, read, and update calendar attributes using the csa_list_calendar_attributes(), csa_read_calendar_attributes(), and csa_update_calendar_attributes() functions. The application can register callback functions for receiving notification of a calendar logon, calendar deletion, update of calendar attributes, addition of a new calendar entry, deletion of a calendar entry, and update of a calendar entry. The callback function is only registered for the duration of the calendar session. In any case, this information may be invaluable for some calendar administration applications.

Entry Management

The CSA interface has a robust set of functions for managing calendar entries. The context of a calendar entry in a calendar session is maintained by the entry handle. This handle provides a token in the CSA functions to distinguish one calendar entry from another. The entry handle is returned by the csa_add_entry() and csa_list_entries() functions. The entry handle is valid for the duration of the calendar session or until the entry is deleted or updated. The entry handle becomes invalid when it is freed by a call to csa_free().

The csa_add_entry() function is used to add new entries to a calendar. The csa_delete_entry() function is used to delete an entry in a calendar. The csa_list_entries() function is used to enumerate the calendar entries that match a particular set of entry attribute criteria. The csa_read_entry_attributes() function is used to get either all or a set of entry attribute values associated with a particular calendar entry.

To add an entry to a calendar, a calendar-enabled application must first establish a session with the calendaring service using the csa_logon() function. Then the application invokes the csa_add_entry() function to specify the new entry. The calendar-enabled application is responsible for composing the attributes used in the csa_add_entry() function. The session is terminated using the csa_logoff() function.

The entry attributes in an individual calendar entry can be enumerated with the csa_list_entry_attributes() function. The values of one or more attributes can be read with the csa_read_entry_attributes() function. Individual entry attributes can be modified with the csa_update_entry_attributes() function.

Memory allocated by the CSA implementation for retrieved calendar information is released by passing the associated memory pointers to the csa_free() function.

Some calendar entries are associated with a recurring activity. The csa_list_entry_sequence() function can be used to enumerate the other recurring calendar entries. This function returns a list of entry handles for the recurring entries.

The CDE calendar server provides support for alarms or reminders to be associated with calendar entries. Reminders can take the form of audio reminders from the terminal speaker, flashing reminders presented on the terminal screen, mail reminders sent to the calendar user, or pop-up reminders presented on the terminal screen. The calendar service manages the reminders, but it is the responsibility of the calendar application to retrieve the reminder information and act on it. The csa_read_next_reminder() function is used to read the information about the next scheduled type of reminder.

Extensions

The major data structures and functions defined in the CSA specification can be extended methodically through extensions. Extensions are used to add additional fields to data structures and additional parameters to a function call. A standard generic data structure has been defined for these extensions. It consists of an item code, identifying the extension; an item data, holding the length of extension data or the data itself; an item reference, pointing to where the extension value is stored or NULL if there is no related item storage; and flags for the extension.

Extensions that are additional parameters to a function call may be input or output. That is, the extension may be passed as input parameters from the application to the CSA service or passed as output parameters from CSA service to the application. If an extension is an input parameter, the application allocates memory for the extension structure and any other structures associated with the extension. If an extension is an output parameter, the CSA service allocates the storage for the extension result, if necessary. In this case, the application must free the allocated storage with a csa_free() call.

If an extension that is not supported is requested, CSA_E_UNSUPPORTED_FUNCTION_EXT is returned.

About the CDE Implementation

The CDE implementation of the CSA API consists of a library which provides access to the CDE calendar server. ONC RPC is used for communication between the library and the server. The calendar server in the CDE implementation is a version 5 server which supports calendar protocol versions 2 to 5 and data versions 3 and 4. Calendar protocol versions 2 to 4 and data version 3 are for backward compatibility to OpenWindows Calendar Manager. Calendar protocol version 5 and data version 4 support the CSA interface and data extensibility.

Access models supported

Two access models are supported by the calendar API. The access model specified in the XAPIA CSA specification is supported for data version 4 only. The OpenWindows Calendar Manager access model is supported for data versions 1 to 3. In the OpenWindows Calendar Manager access model, the accessibility of a calendar is controlled by an access list which specifies who has what access rights. Three access rights are defined: CSA_X_DT_BROWSE_ACCESS (user can list and read calendar entries), CSA_X_DT_INSERT_ACCESS (user can insert calendar entries), and CSA_X_DT_DELETE_ACCESS (user can delete calendar entries). Since the calendar API allows access to calendars of all versions, the programmer should interpret the access rights contained in an access list using the correct access model depending on the data version.

When a calendar is created, unless an access list is specified during creation, the default access list consists of one entry with "world" as the user name; the associated access right is "browse public entries." The user name "world" is a special name which means all users.

By default, a user with the same user name as the owner of the calendar can access the calendar with full owner's access from any machine. To have stricter access control, names of the form "owner-user-name@host" can be added to the access list of the calendar. When such an entry is added to the access list, the corresponding access right has to be CSA_OWNER_RIGHTS for data version 4 and (CSA_X_DT_BROWSE_ACCESS|CSA_X_DT_INSERT_ACCESS|CSA_X_DT_DELETE_ACCESS) for data version 3. After such entries are added to the access list, only users from the specified hosts can access the calendar with full owner's rights.

Data Structures

Table 10-3 lists the CSA data structures. See the relevant man page for complete information.

Calendar Attributes

Table 10-4 lists the calendar attributes supported in the CDE implementation. See the relevant man page for more information. The list of calendar attributes is extensible through the extended naming convention.

*specified when the calendar is created and read-only afterwards

**CDE only

The following Calendar attributes are not supported:

CSA_CAL_ATTR_COUNTRY 
CSA_CAL_ATTR_LANGUAGE  
CSA_CAL_ATTR_WORK_SCHEDULE

The following descriptions provide additional information about some of the calendar attributes listed in Table 10-4.

• Access List

  When a new calendar is added and if no access list is specified, the default access list contains a special user world and its corresponding access right is CSA_VIEW_PUBLIC_ENTRIES, which provides access right to list and read calendar entries with public classification. The special user world includes all users.

• Calendar Name

  The calendar name is specified when the calendar is created using csa_add_calendar(). It becomes read-only and cannot be changed after the calendar is created.

• Calendar Owner

  The calendar owner is set to the user who is running the application that calls csa_add_calendar() to create the calendar. It becomes read-only and cannot be changed after the calendar is created.

• Character Set

  The CDE common locale name should be used to set this value.

The followings are CDE-defined calendar attributes:

• Server Version

  This read-only attribute shows the version number of the server managing the calendar. This attribute is a CSA_VALUE_UINT32 type of attribute.

• Data Version

  This read-only attribute shows the data version of the calendar. This attribute is a CSA_VALUE_UINT32 type of attribute.

Entry Attributes

Table 10-5 lists the entry attributes supported in the CDE implementation. See the relevant man page for more information. The list of entry attributes is extensible through the extended naming convention.

* CDE only

** This attribute can be specified and modified for data version 1 to 3, but is read-only for data version 4; for data version 4, the value is derived from the entry attribute CSA_ENTRY_ATTR_RECURRENCE_RULE

***Specified when the entry is added to the calendar and read-only afterwards

The following Entry attributes are not supported:

CSA_ENTRY_ATTR_ATTENDEE_LIST
CSA_ENTRY_ATTR_EXCEPTION_RULE  
CSA_ENTRY_ATTR_RECURRING_DATES 
CSA_ENTRY_ATTR_SEQUENCE_NUMBER

The following descriptions provide additional information about some of the entry attributes listed in Table 10-5.

• Organizer

  The organizer of an entry is set to the user who is running the application that calls csa_add_entry() to add the entry to the calendar. It becomes read-only and cannot be changed after the entry is added.

• Reference Identifier

  The reference identifier of an entry is a string that contains a unique identifier of the entry within the calendar as well as the name and location of the calendar. The format is n:calendar@location where n is a number that uniquely identifies the entry within the calendar, calendar is the name of the calendar, and location is the name of the machine where the calendar is stored.

• Status

  The CDE implementation defines the following additional status values:

CSA_X_DT_STATUS_ACTIVE
CSA_X_DT_STATUS_DELETE_PENDING  	
CSA_X_DT_STATUS_ADD_PENDING 
CSA_X_DT_STATUS_COMMITTED 
CSA_X_DT_STATUS_CANCELLED

• Type

  The value becomes read-only and cannot be changed after the entry is added. The CDE implementation defines the following additional type value:

	CSA_X_DT_TYPE_OTHER

CDE Entry Attributes

The following are CDE-defined entry attributes:

• Show Time

  The value of this attribute indicates whether the start and end time of the entry should be shown to the user. It can be modified using csa_update_entry_attributes(). This attribute is a CSA_VALUE_SINT32 type of attribute.

• Repeat Type

  The frequency of recurrence of the entry, which indicates how often the entry repeats.

  This attribute is a CSA_VALUE_UINT32 type of attribute.

  The following values are defined:

CSA_X_DT_REPEAT_ONETIME
CSA_X_DT_REPEAT_DAILY  
CSA_X_DT_REPEAT_WEEKLY  
CSA_X_DT_REPEAT_BIWEEKLY 
CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY  
CSA_X_DT_REPEAT_MONTHLY_BY_DATE 
CSA_X_DT_REPEAT_YEARLY 
CSA_X_DT_REPEAT_EVERY_NDAY 
CSA_X_DT_REPEAT_EVERY_NWEEK  
CSA_X_DT_REPEAT_EVERY_NMONTH 
CSA_X_DT_REPEAT_MON_TO_FRI  
CSA_X_DT_REPEAT_MONWEDFRI  
CSA_X_DT_REPEAT_TUETHUR
CSA_X_DT_REPEAT_WEEKDAYCOMBO 
CSA_X_DT_REPEAT_OTHER 
CSA_X_DT_REPEAT_OTHER_WEEKLY  
CSA_X_DT_REPEAT_OTHER_MONTHLY 
CSA_X_DT_REPEAT_OTHER_YEARLY

• Repeat Times

  This attribute shows the number of times an entry repeats. This attribute is a CSA_VALUE_UINT32 type of attribute.

• Repeat Interval

  This attribute tells how often an entry with repeat types CSA_X_DT_REPEAT_EVERY_NDAY, CSA_X_DT_REPEAT_EVERY_NWEEK, or CSA_X_DT_REPEAT_EVERY_NMONTH repeats. For example, if the value of this attribute is 3 and the repeat type is CSA_X_DT_REPEAT_EVERY_NWEEK, the entry repeats every three weeks. This attribute is a CSA_VALUE_UINT32 type of attribute.

• Repeat Occurrence Number

  If the entry's repeat type is CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY, this attribute tells in which week the entry repeats. This attribute is a CSA_VALUE_SINT32 type of attribute.

• Sequence End Date

  This entry attribute shows the end date of the sequence. This attribute is a CSA_VALUE_DATE_TIME type of attribute.

Entry Attributes for Recurrence Information

For data versions 1 to 3, the following entry attributes are used to specify recurrence information for an entry. They are all read/write attributes.

CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE
CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES  
CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL 
CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM 
CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE 

For data version 4, entry attributes CSA_ENTRY_ATTR_RECURRENCE_RULE and CSA_ENTRY_ATTR_EXCEPTION_DATES are used to specify recurrence information of a calendar entry. Information in the CSA_ENTRY_ATTR_RECURRENCE_RULE attribute can be queried using the following attributes:

CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE
CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES  
CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL 
CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM 
CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE 

These computed attributes are read-only for data version 4.

Supported Values by Data Version

• CSA_ENTRY_ATTR_STATUS

  This attribute is not supported in data version 1.

  Data versions 2 and 3 support the following values:

CSA_X_DT_STATUS_ACTIVE
CSA_X_DT_STATUS_DELETE_PENDING  
CSA_X_DT_STATUS_ADD_PENDING 
CSA_X_DT_STATUS_COMMITTED 
CSA_X_DT_STATUS_CANCELLED

Data version 4 supports all status values:

CSA_STATUS_ACCEPTED
CSA_STATUS_NEEDS_ACTION  
CSA_STATUS_SENT  
CSA_STATUS_TENTATIVE 
CSA_STATUS_CONFIRMED  
CSA_STATUS_REJECTED  
CSA_STATUS_COMPLETED 
CSA_STATUS_DELEGATED  
CSA_X_DT_STATUS_ACTIVE  
CSA_X_DT_STATUS_DELETE_PENDING 
CSA_X_DT_STATUS_ADD_PENDING  
CSA_X_DT_STATUS_COMMITTED 
CSA_X_DT_STATUS_CANCELLED

• CSA_ENTRY_ATTR_SUBTYPE

  Data versions 1 to 3 support the following values:

CSA_SUBTYPE_APPOINTMENT
CSA_SUBTYPE_HOLIDAY

Data version 4 supports all defined values as well as the following application-defined values:

CSA_SUBTYPE_APPOINTMENT
CSA_SUBTYPE_CLASS  
CSA_SUBTYPE_HOLIDAY  
CSA_SUBTYPE_MEETING 
CSA_SUBTYPE_MISCELLANEOUS  
CSA_SUBTYPE_PHONE_CALL  
CSA_SUBTYPE_SICK_DAY 
CSA_SUBTYPE_SPECIAL_OCCASION  
CSA_SUBTYPE_TRAVEL 
CSA_SUBTYPE_VACATION

• CSA_ENTRY_ATTR_TYPE

  Data versions 1 to 3 support the following values:

CSA_TYPE_EVENT 
CSA_TYPE_TODO  
CSA_X_DT_TYPE_OTHER

Data version 4 supports all defined values:

CSA_TYPE_EVENT 
CSA_TYPE_TODO  
CSA_TYPE_MEMO  
CSA_X_DT_TYPE_OTHER

Only some combinations of type and subtype values--listed below--are supported in data version 1 to 3.

Combinations supported in data version 1:

CSA_TYPE_EVENT with subtype CSA_SUBTYPE_APPOINTMENT  
CSA_X_DT_TYPE_OTHER with no subtype value

Combinations supported in data versions 2 and 3:

CSA_TYPE_EVENT with subtype CSA_SUBTYPE_APPOINTMENT  
CSA_TYPE_EVENT with subtype CSA_SUBTYPE_HOLIDAY  
CSA_TYPE_TODO with no subtype value  
CSA_X_DT_TYPE_OTHER with no subtype value

• CSA_X_ENTRY_ATTR_REPEAT_TYPE

  For data versions 1 to 3, this attribute is used to specify the type of recurrence of an entry.

  Values supported in data versions 1 and 2:

CSA_X_DT_REPEAT_ONETIME
CSA_X_DT_REPEAT_DAILY  
CSA_X_DT_REPEAT_WEEKLY  
CSA_X_DT_REPEAT_BIWEEKLY 
CSA_X_DT_REPEAT_MONTHLY_BY_DATE 
CSA_X_DT_REPEAT_YEARLY

Values supported in data version 3:

CSA_X_DT_REPEAT_ONETIME
CSA_X_DT_REPEAT_DAILY  
CSA_X_DT_REPEAT_WEEKLY  
CSA_X_DT_REPEAT_BIWEEKLY 
CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY  
CSA_X_DT_REPEAT_MONTHLY_BY_DATE 
CSA_X_DT_REPEAT_YEARLY  
CSA_X_DT_REPEAT_EVERY_NDAY 
CSA_X_DT_REPEAT_EVERY_NWEEK  
CSA_X_DT_REPEAT_EVERY_NMONTH 
CSA_X_DT_REPEAT_MON_TO_FRI  
CSA_X_DT_REPEAT_MONWEDFRI  
CSA_X_DT_REPEAT_TUETHUR
CSA_X_DT_REPEAT_WEEKDAYCOMBO 
CSA_X_DT_REPEAT_OTHER

For data version 4, this is a read-only attribute and the value is derived from the entry attribute CSA_ENTRY_ATTR_RECURRENCE_RULE.

General Information About Functions

The following general information applies to all functions:

• Character set restriction

  The calendar attribute, CSA_CAL_ATTR_CHARACTER_SET, is used to store the locale information of the calendar.

All data except textual description passed in the library must be in ASCII format; the library supports single-byte as well as multibyte character strings.

• Type checking for attribute values is provided for the predefined attributes only.

• Entry attributes CSA_ENTRY_ATTR_RECURRENCE_RULE and CSA_ENTRY_ATTR_EXCEPTION_DATES are used to specify recurrence information of a calendar entry. Information in the CSA_ENTRY_ATTR_RECURRENCE_RULE attribute can be queried using the following attributes:

  CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE  
  CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES  
  CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL  
  CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM  
  CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE. 

  These computed attributes are read-only.

• The CSA_calendar_user data structure specifies either a user or a calendar. When specifying a user in an access list, only the user_name field is used and all other fields are ignored. When specifying the calendar to log on to, only the calendar_address field is used and all other fields are ignored. The format is calendar@location where calendar is the name of the calendar and location is the name of the machine where the calendar is stored.

• Attributes of value type CSA_VALUE_ATTENDEE_LIST are not supported and CSA_E_INVALID_ATTRIBUTE_VALUE will be returned if they are specified.

• Although the repeat_count and snooze_time fields in the CSA_reminder data structure are stored in the calendar, the calendar service does not interpret their values and the associated reminder will be returned only once by the server.

• The user interface extension CSA_X_UI_ID_EXT is not supported.

Function Extensions Supported

• Xt Application Context Extension (CSA_X_XT_APP_CONTEXT_EXT)

  - Specify the Xt application context. - Used by csa_register_callback()- Input:

  item_data: Xt application context (XtAppContext)

  - Output: None

• Get User Access Extension (CSA_X_DT_GET_USER_ACCESS_EXT)

  - Get the user's access rights with respect to the calendar. - Used by csa_logon()- Input: none - Output:

  item_data: user's access rights (CSA_flags)

• Get Character Set Calendar Attribute Extension (CSA_X_DT_GET_CAL_CHARSET_EXT)

  - Get the calendar's character set attribute - Used by csa_logon() ()- Input: none - Output:

  item_data: length of character string in item_reference (CSA_uint32) item_reference: character set (CSA_string)

• Get Server Version Calendar Attribute Extension (CSA_X_DT_GET_SERVER_VERSION_EXT)

  - Get server version of the calendar - Used by csa_logon() and csa_list_calendars()- Input: none - Output:

  item_data: server version (CSA_uint32)

• Get Data Version Calendar Attribute Extension (CSA_X_DT_GET_DATA_VERSION_EXT)

  - Get data version of the calendar - Used by csa_logon() ()- Input: none - Output:

  item_data: data version (CSA_uint32)

Administration Functions

This section contains descriptions for the administration functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

• Free: frees memory allocated by the calendaring service.

  Prototype:

CSA_return_code 
csa_free(CSA_buffer								memory  );

Return Codes for csa_free:

CSA_SUCCESS CSA_E_INVALID_MEMORY

• List Calendars: lists the calendars supported by a calendar server.

  Prototype:

CSA_return_code 
csa_list_calendars(CSA_service_reference
  calendar_service,
  CSA_uint32
  *number_names,
  CSA_calendar_user  
  **calendar_names,  CSA_extension          
  *list_calendars_extensions);

A host name where the server runs should be passed in calendar_server.

Return Codes for csa_list_calendars:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_X_DT_E_INVALID_SERVER_LOCATION 
CSA_X_DT_E_SERVICE_NOT_REGISTERED  
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_NOT_SUPPORTED  
CSA_E_SERVICE_UNAVAILABLE

• Logon: logs on to the calendar service and establishes a session with a calendar.

  Prototype:

CSA_return_code

csa_logon(
  CSA_service_reference	calendar_service,
  CSA_calendar_user	      *user,
  CSA_string            	password,
  CSA_string             	character_set,
  CSA_string            	required_csa_version,
  CSA_session_handle     	*session,
  CSA_extension         	*logon_extensions);

The following arguments are not used: calendar_service, password, character_set, and required_csa_version.

The calendar_address field of the CSA_calendar_user structure pointed to by user specifies the calendar to log on to. The format is calendar@location where calendar is the name of the calendar and location is the host name where the calendar is stored.

Return Codes for csa_logon:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER 
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_CALENDAR_NOT_EXIST  
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_NO_AUTHORITY 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE  
CSA_E_SERVICE_UNAVAILABLE 
CSA_X_DT_E_BACKING_STORE_PROBLEM

• Logoff: terminates a session with a calendar.

  Prototype:

CSA_return_code
 csa_logoff(
  CSA_session_handle							session,
  CSA-extension							*logoff_extensions);

Return Codes for csa_logoff:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY 
CSA_E_INVALID_SESSION_HANDLE

• Query Configuration: determines information about the installed CSA configuration.

  Prototype:

CSA_return_code

 csa_query_configuration(
  CSA_session_handle     session,
  CSA_enum               item,
  CSA_buffer             *reference,
  CSA_extension          *query_configuration_extensions);

The following items are not supported by this implementation of CDE:

CSA_CONFIG_CHARACTER_SET
CSA_CONFIG_LINE_TERM  CSA_CONFIG_VER_IMPLEM

Return Codes for csa_query_configuration:

CSA_SUCCESS 
CSA_E_INVALID_ENUM  
CSA_E_INVALID_PARAMETER  
CSA_E_INSUFFICIENT_MEMORY 
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_UNSUPPORTED_ENUM 
CSA_E_UNSUPPORTED_FUNCTION_EXT

Calendar Management Functions

This section contains descriptions for the calendar management functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

• Add calendar: adds a calendar to the calendar service.

  Prototype:

CSA_return_code

 csa_add_calendar(
  CSA_session_handle      session,
  CSA_calendar_user       *user,
  CSA_uint32              number_attributes,
  CSA_attribute           *calendar_attributes, 
  CSA_extension           *add_calendar_extensions);

The first argument, session, is ignored.

The calendar_address field of the CSA_calendar_user structure pointed to by user specifies the name and the location of the calendar to be created. The format is calendar@location where calendar is the name of the calendar and location is the host name where the calendar is to be stored; for example, my_calendar@my_host.

Return Codes for csa_add_calendar:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_CALENDAR_EXISTS  
CSA_E_NO_AUTHORITY 
CSA_E_READONLY  
CSA_E_INVALID_ATTRIBUTE  
CSA_E_INVALID_ATTRIBUTE_VALUE 
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_INVALID_DATE_TIME  
CSA_E_DISK_FULL 
CSA_X_DT_E_BACKING_STORE_PROBLEM  
CSA_X_DT_E_INVALID_SERVER_LOCATION 
CSA_X_DT_E_SERVICE_NOT_REGISTERED  
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• Call Callbacks: forces the invocation of the callback functions associated with the specified callback list(s).

  Prototype:

CSA_return_code
 csa_call_callbacks(
   CSA_session_handle								session,
   CSA_flags								reason, 
   CSA_extension								*call_callbacks_extensions);

Return Codes for csa_call_callbacks:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT  
CSA_E_INVALID_FLAG 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_X_DT_E_MT_UNSAFE

• Delete Calendar: deletes a calendar from the calendar service.

  Prototype:

CSA_return_code
  csa_delete_calendar(
   CSA_session_handle				session,
   csa_extension				 		*delete_calendar_extensions);

Return Codes for csa_delete_calendar:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NOT_SUPPORTED 
CSA_E_NO_AUTHORITY  
CSA_X_DT_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• List Calendar Attributes: lists the names of the calendar attributes associated with a calendar.

  Prototype:

CSA_return_code
 csa_list_calendar_attributes(
   CSA_session_handle           session,
   CSA_uint32                   *number_names,
   CSA_attribute_reference      **calendar_attributes_names, 
   CSA_extension                *list_calendar_attributes_extensions);

Return Codes for csa_list_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NOT_SUPPORTED 
CSA_E_NO_AUTHORITY 
CSA_X_DT_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• Read Calendar Attributes: reads and returns the calendar attribute values for a calendar.

  Prototype:

CSA_return_code
 csa_read_calendar_attributes(
   CSA_session_handle      session,
   CSA_uint32              number_names,
   CSA_attribute_reference *attribute_names,
   CSA_uint32              *number_attributes,
   CSA_attribute           **calendar_attributes,
   CSA_extension				 *read_calendar_attributes_extensions);

Return Codes for csa_read_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• Register Callback Functions: registers the callback function to be invoked with the specified type of updates in the calendar.

  Prototype:

CSA_return_code
csa_register_callback(
  CSA_session_handle     session,
  CSA_flags              reason,
  CSA_callback           callback,
  CSA_buffer             client_data,
  CSA_extension          *register_callback_extensions);

Return Codes for csa_register_callback:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_INVALID_FLAG 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• Unregister Callback Functions: unregisters the specified callback function.

  Prototype:

CSA_return_code
 csa_unregister_callback(
  CSA_session_handle     session,
  CSA_flags              reason,
  CSA_callback           callback,
  CSA_buffer             client_data,
  CSA_extension          *unregister_callback_extensions);

Return Codes for csa_unregister_callback:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_INVALID_FLAG 
CSA_E_CALLBACK_NOT_REGISTERED  
CSA_E_FAILURE

• Update Calendar Attributes: updates the calendar attribute values for a calendar.

  Prototype:

CSA_return_code csa_update_calendar_attributes(
  CSA_session_handle     session,
  CSA_uint32             number_attributes,
  CSA_attribute          *calendar_attributes,
  CSA_extension          *update_calendar_attributes_extensions);

Return Codes for csa_update_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NO_AUTHORITY 
CSA_E_INVALID_ATTRIBUTE_VALUE  
CSA_E_INVALID_ATTRIBUTE 
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_READONLY  
CSA_E_INVALID_DATE_TIME 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

Entry Management Functions

This section contains descriptions for the entry management functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

• Add Entry: adds an entry to the specified calendar.

  Prototype:

CSA_return_code 
csa_add_entry(
  CSA_session_handle				session,
  CSA_uint32						number_attributes,
  CSA_attribute					*entry_attributes,
  CSA_entry_handle				*entry,
  CSA_extension					*add_entry_extensions);

Return Codes for csa_add_entry:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NO_AUTHORITY 
CSA_E_READONLY  
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_INVALID_ATTRIBUTE 
CSA_E_INVALID_ATTRIBUTE_VALUE  
CSA_E_INVALID_DATE_TIME  
CSA_E_INVALID_RULE 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

Minimum set of attributes to be specified when adding an entry:

For data version 1-3:

Must specify:

CSA_ENTRY_ATTR_START_DATE
CSA_ENTRY_ATTR_TYPE

Default will be set if these are not specified:

CSA_ENTRY_ATTR_CLASSIFICATION (CSA_CLASS_PUBLIC)
CSA_ENTRY_ATTR_STATUS (CSA_X_DT_STATUS_ACTIVE) 
CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type
      CSA_TYPE_EVENT;
this attribute is not supported for type
      CSA_TYPE_TODO)
CSA_ENTRY_ATTR_SUMMARY (NULL string)
CSA_X_ENTRY_ATTR_REPEAT_TYPE (CSA_X_REPEAT_ONETIME) 
CSA_X_ENTRY_ATTR_SHOWTIME (1 => true)

For data version 4:

Must specify:

CSA_ENTRY_ATTR_START_DATE
CSA_ENTRY_ATTR_TYPE

Default will be set if these are not specified:

CSA_ENTRY_ATTR_CLASSIFICATION
(CSA_CLASS_PUBLIC)
  CSA_ENTRY_ATTR_STATUS (CSA_X_STATUS_ACTIVE) 
CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type
      CSA_TYPE_EVENT) 
CSA_ENTRY_ATTR_SUMMARY (NULL string)
  CSA_X_ENTRY_ATTR_SHOWTIME (1 =>true)

• Delete Entry: deletes an entry from the specified calendar.

  Prototype:

CSA_return_code
 csa_delete_entry(
  CSA_session_handle     session,
  CSA_entry_handle       entry,
  CSA_enum               delete_scope,
  CSA_extension          *delete_entry_extensions);

Return Codes for csa_delete_entry:

CSA_SUCCESS 
CSA_E_INVALID_ENUM  
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_E_INVALID_ENTRY_HANDLE  
CSA_E_NO_AUTHORITY  
CSA_X_DT_E_ENTRY_NOT_FOUND 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

• List Entries: lists the calendar entries that match all the attribute search criteria.

  Prototype:

CSA_return_code
 csa_list_entries(
  CSA_session_handle     session,
  CSA_uint32             number_attributes,
  CSA_attribute          *entry_attributes,
  CSA_enum               *list_operators,
  CSA_uint32             *number_entries,
  CSA_entry_handle       **entries,
  CSA_extension          *list_entries_extensions);

Note the following about the operators specified in list_operators:

Only the operators CSA_MATCH_ANY and CSA_MATCH_EQUAL_TO are supported for the attribute value types CSA_VALUE_REMINDER, CSA_VALUE_CALENDAR_USER, and CSA_VALUE_DATE_TIME_RANGE.

Only the operators CSA_MATCH_ANY, CSA_MATCH_EQUAL_TO, CSA_MATCH_NOT_EQUAL_TO, and CSA_MATCH_CONTAIN are supported for the attribute value type CSA_VALUE_STRING. The operator CSA_MATCH_CONTAIN only applies to CSA_VALUE_STRING type of attributes.

Matching of attributes with the value types CSA_VALUE_OPAQUE_DATA, CSA_VALUE_ACCESS_LIST, CSA_VALUE_ATTENDEE_LIST, and CSA_VALUE_DATE_TIME_LIST are not supported. The only exception is the attribute CSA_ENTRY_ATTR_REFERENCE_IDENTIFIER. The operator CSA_MATCH_EQUAL_TO is supported for this attribute.

Return Codes for csa_list_entries:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE  CSA_E_NO_AUTHORITY 

CSA_E_INVALID_ATTRIBUTE_VALUE  CSA_E_INVALID_DATE_TIME  CSA_E_INVALID_ENUM 

CSA_E_UNSUPPORTED_ENUM  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• List Entry Attributes: lists the names of the entry attributes associated with the specified entry.

  Prototype:

CSA_return_code
 csa_list_entry_attributes(
  CSA_session_handle					session,
  CSA_entry_handle					entry,
  CSA_uint32							*number_names,
  CSA_attribute_reference			**entry_attribute_names,
  CSA_extension						*list_entry_attributes_extensions);

Return Codes for csa_list_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM  CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED  CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• List Entry Sequence: lists the recurring calendar entries that are associated with a calendar entry.

  Prototype:

CSA_return_code 
csa_list_entry_sequence(
  CSA_session_handle				session,
  CSA_entry_handle				entry,
  CSA_date_time_range			time_range,
  CSA_uint32						*number_entries,
  CSA_entry_handle				**entry_list,
  CSA_extension					*list_entry_sequences_extensions);

CSA_E_INVALID_PARAMETER is returned if the specified entry is a one-time entry.

Return Codes for csa_list_entry_sequence:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE CSA_E_INVALID_DATE_TIME CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED CSA_X_DT_E_SERVER_TIMEOUT CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• Read Entry Attributes: reads and returns the calendar entry attribute values for a specified entry.

  Prototype:

CSA_return_code 
csa_read_entry_attributes(
  CSA_session_handle					session,
  CSA_entry_handle					entry,
  CSA_uint32							number_names,
  CSA_attribute_reference		   *attribute_names,
  CSA_uint32						   *number_attributes,
  CSA_attribute					   **entry_attributes,
  CSA_extension						*read_entry_attributes_extensions);

Return Codes for csa_read_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM  CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED  CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• Read Next Reminder: reads the next reminder of the given type in the specified calendar relative to a given time.

  Prototype:

CSA_return_code
 csa_read_next_reminder(
  CSA_session_handle					session,
  CSA_uint32					   	number_names,
  CSA_attribute_reference      *reminder_names,
  CSA_date_time					  given_time,
  CSA_uint32						  *number_reminders,
  CSA_reminder_reference       **reminder_references,
  CSA_extension					  *read_next_reminder_extensions);

Return Codes for csa_read_next_reminder:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_DATE_TIME  CSA_E_NO_AUTHORITY  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• Update Entry Attribute: updates the calendar entry attributes.

  Prototype:

CSA_return_code
 csa_update_entry_attributes(
  CSA_session_handle					session,
  CSA_entry_handle					entry,
  CSA_enum								update_scope,
  CSA_boolean							update_propagation,
  CSA_uint32							number_attributes,
  CSA_attribute						*entry_attributes,
  CSA_entry_handle					*new_entry,
  CSA_extension						*update_entry_attributes_extensions);

Update propagation is not supported; the update_propagation argument should be set to CSA_FALSE.

Return Codes for csa_update_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_E_NO_AUTHORITY  CSA_E_READONLY 

CSA_E_INVALID_ENUM  CSA_E_UNSUPPORTED_ATTRIBUTE  CSA_E_INVALID_ATTRIBUTE 

CSA_E_INVALID_ATTRIBUTE_VALUE  CSA_E_INVALID_DATE_TIME  CSA_E_INVALID_RULE 

CSA_E_DISK_FULL  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

• Unsupported Functions

  The following functions are not supported in CDE and will return CSA_E_NOT_SUPPORTED only:

csa_add_event 
csa_add_memo  
csa_add_todo  
csa_free_time_search  
csa_look_up  
csa_restore 
csa_save  

Code Examples

Listing and Printing Calendars

Example 10-1 Listing and Printing Calendars Supported by Server

Example:
List and print out the calendars supported by a server.
 	   Free memory returned by a CSA function. 
list_calendar() 
{
 	CSA_return_code		stat;
	CSA_uint32		i, number;
 	CSA_calendar_user	*calendars;
 	char			*host;

  	/*specify some machine in the network */
 	host = "somehost";

  	stat= csa_list_calendars(host, &number, &calendars, NULL);
  	for (i = 0; i< number; i++) {
 		/* the calendar_address field contains the address of the
 		 * the calendar in the format "user@host" 		 */
 	printf("%d: %s\n", i, calendars[i].calendar_address); 	
   }

  	/* Example: free memory returned by a CSA function
 	 * free the memory returned by csa_list_calendars above
 	 */
 	stat = csa_free(calendars); 
}

Adding a Calendar

Example 10-2 Adding a Calendar Named "activity" to Host "host1"

#include <csa/csa.h>  

CSA_access_rights *setup_access_list() {
 	CSA_access_rights	*ptr1, *ptr2;
  	/* Allow any user to view public and confidential entries and
 	 * user "user1" to view and insert public entries.
 	 * The special user name "world" means any user.
   */

  	ptr2 = (CSA_access_rights *)calloc(1, sizeof(CSA_access_rights));
 	ptr2->user = (CSA_calendar_user *)calloc(1, sizeof(CSA_calendar_user));
 	ptr2->user->user_name = strdup("world");
 	ptr2->user->user_type = CSA_USER_TYPE_INDIVIDUAL;
 	ptr2->flags = CSA_VIEW_PUBLIC_ENTRIES | CSA_VIEW_CONFIDENTIAL_ENTRIES;
  	ptr1 = (CSA_access_rights *)calloc(1, sizeof(CSA_access_rights));
 	ptr1->user = (CSA_calendar_user *)calloc(1, sizeof(CSA_calendar_user));
 	ptr1->user->user_name = strdup("user1");
 	ptr1->user->user_type = CSA_USER_TYPE_INDIVIDUAL;
 	ptr1->flags = CSA_VIEW_PUBLIC_ENTRIES | CSA_INSERT_PUBLIC_ENTRIES;
 	ptr1->next = ptr2; 
} 

void destroy_access_list(CSA_access_rights *list) 
{
 	CSA_access_rights	*ptr;

  	while (list != NULL) {
 		ptr = list->next;

  		if (list->user) {
 			if (list->user->user_name)
 				free(list->user->user_name);
 			free(list->user);
 		} 		free(list);
  		list = ptr;
 	}
} 
add_calendar() 
{
 	CSA_return_code		stat;
 	CSA_calendar_user	caddr;
 	CSA_attribute		attr;
 	CSA_attribute_value	attr_val;

  	/* Specify the calendar to add */

 	caddr.user_name = NULL;
 	caddr.user_type = NULL;
 	caddr.calendar_address = "activity@host1";
 	caddr.calendar_user_extensions = NULL;

  	/* set up the access list */
 	attr_val.type			= CSA_VALUE_ACCESS_LIST;
 	attr_val.item.access_list_value	= setup_access_list();
 	attr.name			= CSA_CAL_ATTR_ACCESS_LIST;
 	attr.value			= &attr_val;
 	attr.attribute_extensions	= NULL;
  	stat = csa_add_calendar(NULL, &caddr, 1, &attr, NULL);
  	destroy_access_list(attr_val.item.access_list_value);
}

Logging on to a Calendar

Example 10-3 Logging on to a Calendar

CSA_session_handle	cal;

logon() 
{
  CSA_return_code		stat;
  CSA_calendar_user	caddr
;  CSA_flags		access;
  CSA_extension		logon_exts[2];
  CSA_X_COM_support	check_support[2];

  /* Specify the calendar to logon to */
 caddr.user_name = NULL;
 caddr.user_type = CSA_USER_TYPE_INDIVIDUAL;
caddr.calendar_address = "user@host";
caddr.calendar_user_extensions = NULL;

 /* Specify the get user access extension (CSA_X_DT_GET_USER_ACCESS_EXT)
  * to retrieve the user's access right with respect to the calendar.
  */
 logon_exts[0].item_code		= CSA_X_DT_GET_USER_ACCESS_EXT;
 logon_exts[0].item_data		= 0;
 logon_exts[0].item_reference	= NULL;
 logon_exts[0].extension_flags	= NULL;

  /* Specify the CSA_X_COM_SUPPORT_EXT extension to check
   * whether the CSA_X_XT_APP_CONTEXT_EXT extension and the
   * CSA_X_UI_ID_EXT extension are supported.
   */
  check_support[0].item_code	= CSA_X_XT_APP_CONTEXT_EXT;
check_support[0].flags		= NULL;
 check_support[1].item_code	= CSA_X_UI_ID_EXT;
 check_support[1].flags		= NULL;
  logon_exts[1].item_code		= CSA_X_COM_SUPPORT_EXT;
 logon_exts[1].item_data		= 2;
 logon_exts[1].item_reference	= (CSA_buffer)check_support;
 logon_exts[0].extension_flags	= CSA_EXT_LAST_ELEMENT;

  stat = csa_logon(NULL, &caddr, NULL, NULL, NULL, &cal, logon_exts);

  if (stat == CSA_SUCCESS) {
  access = (CSA_flags)get_access_ext.item_data;
   if (check_support[0].flag & CSA_X_COM_SUPPORTED)
   printf("The CSA_X_XT_APP_CONTEXT_EXT extension is supported\n");
   if (check_support[1].flag & CSA_X_COM_SUPPORTED)
   printf("The CSA_X_UI_ID_EXT extension is supported\n");
  }
 }

Terminating a Calendar Session

Example 10-4 Terminating a Calendar Session

logoff() 
{
 	CSA_return_code		stat;

  	/* When the session is no longer needed, it can be terminated by
 	 * calling csa_logoff.
 	 * Terminate the session returned by csa_logon in the previous
 	 * example.
 	 */
 	stat = csa_logoff(cal, NULL); 
}

Deleting a Calendar

Example 10-5 Deleting a Calendar

delete_calendar() 
{
 	/* After a calendar session is established by calling csa_logon(),
 	 * a calendar can be deleted using csa_delete_calendar().
 	 */
 	CSA_return_code		stat;
  	stat = csa_delete_calendar(cal, NULL);
} 

Adding a Calendar Entry

Example 10-6 Adding a Calendar Entry

#include <csa/csa.h>  

CSA_return_code		stat;
CSA_session_handle	cal;
CSA_attribute		attrs[9];
CSA_attribute_value	attr_val[9];
CSA_reminder		audio;
CSA_reminder		mail;
CSA_entry_handle	new_entry;
int			i;

i = 0;

/* The start date attribute. This attribute has no default
  * value and must be specified.
  * A CSA_date_time value is a UTC based date and time value
  * expressed in the ISO 8601 standard.
  */
attrs[i].name = CSA_ENTRY_ATTR_START_DATE;
 attrs[i].value = &attr_val[i];
 attrs[i].attribute_extensions = NULL;
 attr_val[i].type = CSA_VALUE_DATE_TIME;
 attr_val[i].item.date_time_value = iso8601time(time(NULL));
 i++;

/* The end date attribute.
  * If not specified, the entry will not have the end date
  * attribute.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_END_DATE;
 attrs[i].value = &attr_val[i];
 attrs[i].attribute_extensions = NULL;
 attr_val[i].type = CSA_VALUE_DATE_TIME;
 attr_val[i].item.date_time_value = iso8601time(time(NULL) + 3600);
 i++;

/* The classification attribute.
  * If not specified, the default value is CSA_CLASS_PUBLIC.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_CLASSIFICATION;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_UINT32;
attr_val[i].item.sint32_value = CSA_CLASS_CONFIDENTIAL;
i++;  

/* The type attribute. This attribute has no default value and
  * must be specified.
  */
attrs[i].name = CSA_ENTRY_ATTR_TYPE;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_UINT32;
attr_val[i].item.sint32_value = CSA_TYPE_EVENT;
i++;  

/* The sub-type attribute.
  * If not specified, the default value is CSA_SUBTYPE_APPOINTMENT
  */ 
attrs[i].name = CSA_ENTRY_ATTR_SUBTYPE;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = CSA_SUBTYPE_APPOINTMENT; 
i++;  

/* The summary attribute */ 
attrs[i].name = CSA_ENTRY_ATTR_SUMMARY; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = argv6; 
attrs[i].attribute_extensions = NULL; 
i++;  

/* The recurrence rule attribute.
  * If not specified, the entry is a one time entry.
  * The recurrence rule "D1 #3" specifies that the
  * entry is to be repeated daily for 3 days.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_RECURRENCE_RULE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = argv7; 
i++;

/* The audio reminder attribute.
  * The lead time of a reminder is a CSA_time_duration value
  * which is expressed in the ISO 8601 standard.
  * For example, a lead time of 5 minutes is expressed as
  * the string "+PT300S". A negative lead time of 5 minutes
  * is expressed as "-PT300S".
  */ 
attrs[i].name = CSA_ENTRY_ATTR_AUDIO_REMINDER; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_REMINDER; 
attr_val[i].item.reminder_value = &audio; 
memset((void *)&audio, NULL, sizeof(audio)); 
audio.lead_time = "+PT300S"; i++;

/* The mail reminder attribute.
  * The e-mail address is specified in the reminder_data field
  * This reminder has a lead time of one day.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_MAIL_REMINDER; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_REMINDER; 
attr_val[i].item.reminder_value = &mail; 
memset((void *)&mail, NULL, sizeof(mail)); 
mail.lead_time = "+PT86400S"; 
mail.reminder_data.data = "someuser@somehost"; 
mail.reminder_data.size = strlen(mail.reminder_data.data); 
i++;  

/* add an entry with the specified attribute values */ 
stat = csa_add_entry(cal, i, attrs, &newentry, NULL);  
if (stat == CSA_SUCCESS)
 	csa_free((CSA_buffer)newentry);

Looking Up Entries in a Calendar

Example 10-7 Looking up Calendar Entries; Reading Attribute Values

#include <csa/csa.h>  

CSA_return_code		stat; 
CSA_session_handle	cal;
CSA_attribute		attrs[4]; 
CSA_attribute_value	attr_val[4]; 
CSA_enum		ops[4];
CSA_uint32		i; 
CSA_uint32		num_entries;
 CSA_entry_handle	*entries;
CSA_uint32		num_attributes; 
CSA_attribute		*entry_attrs;  

/* find all entries with the following criteria:
  * (all appointments in the month of August 1996 UTC time)
  * start date equals to or after 00:00:00 Aug 1 1996 UTC time
  * and start date before 00:00:00 Sep 1 1996 UTC time
  * and type equals to CSA_TYPE_EVENT
  * and sub-type equals CSA_SUBTYPE_APPOINTMENT
  */  

i = 0;  

/* start date equals to or after 00:00:00 Aug 1 1996 UTC time */ 
attrs[i].name = CSA_ENTRY_ATTR_START_DATE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_DATE_TIME;
attr_val[i].item.date_time_value = "19960801T000000Z"; 
ops[i] = CSA_MATCH_GREATER_THAN_OR_EQUAL_TO; 
i++;  

/* start date before 00:00:00 Sep 1 1996 UTC time */ 
attrs[i].name = CSA_ENTRY_ATTR_START_DATE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_DATE_TIME; 
attr_val[i].item.date_time_value = "19960901T000000Z" 
ops[i] = CSA_MATCH_LESS_THAN; 
i++;  

/* type equals to CSA_TYPE_EVENT */ 
attrs[i].name = CSA_ENTRY_ATTR_TYPE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_UINT32; 
attr_val[i].item.sint32_value = CSA_TYPE_EVENT; 
ops[i] = CSA_MATCH_EQUAL_TO; 
i++;  

/* sub-type equals CSA_SUBTYPE_APPOINTMENT */ 
attrs[i].name = CSA_ENTRY_ATTR_SUBTYPE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = CSA_SUBTYPE_APPOINTMENT; 
ops[i] = CSA_MATCH_EQUAL_TO; 
i++;  

/* do look up */ 
stat = csa_list_entries(csa, i, attrs, ops, &num_entries, &entries, NULL);

  if (stat == CSA_SUCCESS) {
     for (i = 0; i < num_entries; i++) {
  /* get all attribute values of the entry;
   * specifying 0 for number_names and NULL for attribute_names
   * will cause all attribute values to be returned
   */ 	
   stat = csa_read_entry_attributes(cal, entries[i], 0, NULL,
       &num_attributes, &entry_attrs,
       NULL); 	if (stat == CSA_SUCCESS) {
      /* use the returned attribute values,
       * free the memory when done
       */
      csa_free(entry_attrs);
  } else {
      /* handle error */
  }
     }
 } else {
     /* handle error */ 
}   

Example: Change the end time of the returned appointments to be
   one hour later. 

CSA_attribute_reference	name = CSA_ENTRY_ATTR_END_DATE; 
char   buffer[80]; 
time_t   endtime; 
CSA_entry_handle new_entry;  

for (i = 0; i < num_entries; i++) {
     /* get the end time of the appointment */
     stat = csa_read_entry_attributes(cal, entries[i], 0, &name,
         &num_attributes, &entry_attrs, NULL);
     if (stat == CSA_SUCCESS) {
 /* change the end time to be one hour later */
from_iso8601_time(entry_attrs[0].value->item.date_time_value, &endtime);
endtime += 60*60 /* number of second in an hour */
to_iso8601_time(endtime, buffer);
 attrs[0].name = CSA_ENTRY_ATTR_END_DATE;
 attrs[0].value = &attr_val[i];
attrs[0].attribute_extensions = NULL;	
 attr_val[0].type = CSA_VALUE_DATE_TIME;
attr_val[0].item.date_time_value = buffer;
 stat = csa_update_entry_attributes(cal, entries[0], CSA_SCOPE_ALL,
         CSA_FALSE, 1, attrs, &new_entry,
       NULL);
 if (stat == CSA_SUCCESS) {
     csa_free(new_entry);
 } else {
     /* handle error */
 }
  csa_free(entry_attrs);
      } else {
      /* handle error */
     } 
}

Updating a Calendar Entry

Example 10-8 Changing End Time of Returned Appointments: One Hour Later

CSA_attribute_reference	name = CSA_ENTRY_ATTR_END_DATE; 
char			buffer[80]; 
time_t			endtime; 
CSA_entry_handle	new_entry;  

for (i = 0; i < num_entries; i++) {
     /* get the end time of the appointment */
     stat = csa_read_entry_attributes(cal, entries[i], 0, &name,
          &num_attributes, &entry_attrs, NULL);
     if (stat == CSA_SUCCESS) {
  /* change the end time to be one hour later */
  from_iso8601_time(entry_attrs[0].value->item.date_time_value, &endtime);
  endtime += 60*60 /* number of second in an hour */
  to_iso8601_time(endtime, buffer);

   attrs[0].name = CSA_ENTRY_ATTR_END_DATE;
  attrs[0].value = &attr_val[i];
  attrs[0].attribute_extensions = NULL;
  attr_val[0].type = CSA_VALUE_DATE_TIME;
  attr_val[0].item.date_time_value = buffer;
   stat = csa_update_entry_attributes(cal, entries[0], CSA_SCOPE_ALL,
         CSA_FALSE, 1, attrs, &new_entry,
         NULL); 	if (stat == CSA_SUCCESS) {
      csa_free(new_entry);
  } else {
      /* handle error */
  }
   csa_free(entry_attrs);
      } else {
      /* handle error */ 
    }
}

Registering Callback and Keep Reminders

/* The example code shows the usage of csa_register_callback,
  * csa_read_next_reminder, and csa_call_callbacks.
  * The skeleton code registers a callback routine for
  * events CSA_CB_ENTRY_ADDED, CSA_CB_ENTRY_DELETED, and
  * CSA_CB_ENTRY_UPDATED; and another callback routine for the
  * CSA_CB_CALENDAR_ATTRIBUTE_UPDATED event.
  * It also shows how to set up a timer for reminder delivery.
  * Two utilities routines for conversion between time representation
  * in the ISO 8601 format and the tick representing time in seconds
  * since 00:00:00 UTC 1/1/70 are also included.
  */ 

 #include <csa/csa.h> 
#include <time.h> 
#include <unistd.h>  

CSA_session_handle	cal;	 /* a calendar session */ 
time_t			run_time; /* the time the reminders is to be run */ 
CSA_uint32		num_rems; /* number of reminders returned */ 
CSA_reminder_reference *rems;   /* an array of reminder information */  

void 
set_up_callback_handler() 
{
 	CSA_return_code		stat;
 	CSA_flags		flags;

  	/* Xt based applications can use the CSA_X_XT_APP_CONTEXT_EXT
 	 * extension to specify the Xt application context so that
 	 * callback routines will be invoked asynchronously
 	 *
 	 *	CSA_extension callback_ext;
 	 *	callback_ext.item_code = CSA_X_XT_APP_CONTEXT_EXT;
 	 * 	callback_ext.item_data = (CSA_uint32)application_context;
 	 *	callback_ext.extension_flags = CSA_EXT_LAST_ELEMENT;
 	 *
 	 * Pass the callback_ext as the last parameter to
 	 * csa_register_callback.
 	 */

  	flags = CSA_CB_ENTRY_ADDED|CSA_CB_ENTRY_DELETED|CSA_CB_ENTRY_UPDATED;
 	stat = csa_register_callback(cal, flags, entry_update_callback,
 		NULL, NULL);

  	if (stat != CSA_SUCCESS) {
 		/* error handling code */
 	}

  	stat = csa_register_callback(cal, CSA_CB_CALENDAR_ATTRIBUTE_UPDATED,
 		calendar_update_callback, NULL, NULL);
  	if (stat != CSA_SUCCESS) {
 		/* error handling code */
 	} 
}  

/*  * This routine polls the library and causes the registered
  * callback to be invoked if the interested event has occurred.
  * If an application does not use the CSA_X_XT_APP_CONTEXT_EXT
  * extension to set up asynchronously callback invocation,
  * it needs to call csa_call_callbacks to force the invocation
  * of callbacks.
  */ 

check_events(CSA_flags event)
{
 	csa_call_callbacks(cal, event, NULL); 
}

  /*
  * This is the callback routine for events CSA_CB_ENTRY_ADDED,
  * CSA_CB_ENTRY_ADDED, and CSA_CB_ENTRY_UPDATED.
  */ 
void 
entry_update_callback(
 	CSA_session_handle	cal,
 	CSA_flags		flags,
 	CSA_buffer		call_data,
 	CSA_buffer		client_data,
 	CSA_extension		*ext) 
{
 	/* An entry is either added, deleted or updated.
 	 * Possible things to do in this callback routine:
	 *
 	 * 1. Update the calendar view, or
 	 * 2. If this is your own calendar, update reminder information.
 	 *
 	 * The sample code in this routine updates reminder information
 	 */ 	reset_reminder();
}

  /*
  * This is the callback routine for the CSA_CB_CALENDAR_ATTRIBUTE_UPDATED
  * event
  */ 
void 
calendar_update_callback(
 	CSA_session_handle	cal,
 	CSA_flags		flags,
 	CSA_buffer		call_data,
 	CSA_buffer		client_data,
 	CSA_extension		*ext) 
{
 	/* update calendar attributes */ 
}

   /*
  * This routine updates reminder information:
  *	- get rid of existing information if any
  *	- call csa_read_next_reminder() to get the next
  *	 reminder to deliver
  *	- check the run time and set timer
  */ 
void 
reset_reminder() {
 	CSA_return_code		stat;
 	time_t			current_time;
 	char			isotime[BUFSIZ];
 	CSA_uint32		number_reminders;
 	CSA_reminder_reference	*reminders;
 
  	current_time = time(NULL);

  	/* get rid of existing information */
 	if (rems) {
 		/* this comparison is to make sure that we don't lose
 		 * any reminders whose run time is between the last
 		 * run time and the current time
 		 */
 		if (current_time > run_time)
 			current_time = run_time;

  		csa_free((CSA_buffer)rems);
 	}

 	to_iso8601_time(current_time, isotime);
 	stat = csa_read_next_reminder(cal, 0, NULL, isotime,
 		&number_reminders, &reminders, NULL);

  	if (stat == CSA_SUCCESS && num_rems > 0) {
 		num_rems = number_reminders;
 		rems = reminders;

  		/* Set timer to deliver the reminder.
 		 * sigset() should be used to set up the signal
 		 * disposition for the SIGALRM signal.
 		 */
 		from_iso8601_time(reminders[0].run_time, &run_time);
 		remain = run_time - time(NULL);
 		alarm((remain > 0) ? remain : 1);

  		/* Xt based application can set the timer using
 		 * XtAppAddTimeOut
 		 */
 	}
}
  
/*
  * This routine converts a time value in the iso8601 format to
  * a tick (representing time in seconds since 00:00:00 UTC, 1/1/70).
  * The tick is adjusted to the local time.
  */ int from_iso8601_time(char *buf, time_t *tick_out) 
{
  	int		year, month, day, hour, min, sec;
 	struct tm	time_str;

  	sscanf(buf, "%4d%2d%2dT%2d%2d%2dZ",
 	    &year, &month, &day, &hour, &min, &sec);

  	time_str.tm_year	= year - 1900;
 	time_str.tm_mon		= month - 1;
 	time_str.tm_mday	= day;
 	time_str.tm_hour	= hour;
 	time_str.tm_min		= min;
 	time_str.tm_sec		= sec;
 	time_str.tm_isdst	= -1;
  	*tick_out = mktime(&time_str);

  	if (*tick_out != (long)-1) {

  		/* adjust for local time zone */
 		if (time_str.tm_isdst == 0)
 			*tick_out -= timezone;
 		else
 			*tick_out -= altzone;
  		return(0);
 	} else
 		return(-1); 
}  

/*
  * This routine converts a tick (representing time in seconds
  * since 00:00:00 UTC, 1/1/70) to the iso8601 format.
  */ 
int 
to_iso8601_time(time_t tick, char *buf_out) 
{
 	struct tm	time_str;
  	if (gmtime_r(&tick, &time_str)) {

  		/* format string forces fixed width (zero-padded) fields */
 		sprintf(buf_out, "%04d%02d%02dT%02d%02d%02dZ",
 			time_str.tm_year + 1900,
 			time_str.tm_mon + 1,
 			time_str.tm_mday,
 			time_str.tm_hour,
 			time_str.tm_min,
 			time_str.tm_sec);
  		return (0);
 	} else {
 		return (-1);
 	} 
}