APIsLabel Builderlabel APIsLabel BuilderGUIsLabel BuilderSolaris Trusted Extensions provides a set of Motif based APIs. You can use these interfaces to create an interactive GUI to build valid sensitivity labels or clearances from user input. These interfaces are called the Label Builder APIs. These APIs are most often called from within administrative applications.The Label Builder GUIs are used in a system that is configured with Solaris Trusted Extensions. The Solaris Trusted Extensions User’s Guide describes these interfaces from the end user's point of view, as well as the functionality that is provided by the Label Builder library routines.For examples of how the Trusted Extensions APIs are used in the Solaris OS, see the Solaris source code. Go to the Open Solaris web site and click Source Browser in the left navigation bar. Use the Source Browser to search through the Solaris source code.This chapter covers the following topics:APIs for Label Builder GUIs Creating an Interactive User Interface Online Help for Label Builder Label BuilderAPIs tsol_lbuild_destroy routinedeclaration tsol_lbuild_create routinedeclaration Label Builderdeclarations tsol_lbuild_set routinedeclaration tsol_lbuild_get routinedeclaration library routinestsol_lbuild_create library routinestsol_lbuild_destroy library routinestsol_lbuild_get library routinestsol_lbuild_set Label Builderlibraries Label Builderheader files compileLabel Builder libraries libraries, compileLabel Builder APIs header filesLabel Builder APIs To use the APIs that are described in this section, you need to include the following header file:#include <Dt/ModLabel.h>The Label Builder examples compile with the lDtTsol and ltsol library options.The following APIs are available for building label GUIs. The data types and parameter lists are described in Creating an Interactive User Interface.ModLabelData *tsol_lbuild_create(Widget widget, void (*event_handler)() ok_callback, lbuild_attributes extended_operation, ..., NULL);The tsol_lbuild_create routine creates the GUI and returns a pointer variable of type ModLabeldata, which contains information about the user interface. This information is a combination of values passed in the tsol_lbuild_create input parameter list, default values for information not provided, and information about the widgets that the Label Builder uses to create the user interface.The LBUILD_WORK_SL and LBUILD_WORK_CLR operation values are not valid for tsol_lbuild_create because these values are set from input that is supplied by the user.You can use the tsol_lbuild_get and tsol_lbuild_set routines to obtain and set extended operations and values. However, these routines cannot be used for widget information, which is accessed directly by referencing fields in the ModLabelData structure. See the labelbuilder3TSOL man page. void tsol_lbuild_destroy(ModLabelData *lbdata);The tsol_lbuild_destroy routine destroys the ModLabelData structure that is returned by the tsol_lbuild_create routine. void *tsol_lbuild_get(ModLabelData *lbdata, lbuild_attributes extended_operation);The tsol_lbuild_get routine accesses the user interface information that is created by tsol_lbuild_create and stored in the ModLabelData structure. void tsol_lbuild_set(ModLabelData *lbdata, lbuild_attributes extended_operation, ..., NULL);The tsol_lbuild_set routine changes the user interface information that is created by tsol_lbuild_create and stored in the ModLabelData structure. The LBUILD_WORK_SL and LBUILD_WORK_CLR operation values are not valid for tsol_lbuild_set because these values are set from input that is supplied by the user. The following figure shows a GUI similar to the one created by the code that follows the figure. The main program creates a parent form (form) with one button (display). The button callback shows the Label Builder dialog box that is created by the call to the tsol_lbuild_create routine. See the tsol_lbuild_create3TSOL man page.

Window shows the parts of a Label Builder. Callouts show dialog box title, user field, label build field, and OK button callback function.

code examplesLabel Buildertsol_lbuild_set routinecode exampletsol_lbuild_create routinecode exampletsol_lbuild_get routinecode exampleThe Label Builder dialog box appears when you click the Show button in the parent form. The callouts indicate where the parameters passed to the tsol_lbuild_create routine appear in the Label Builder dialog box. See the tsol_lbuild_create3TSOL man page.The following code creates a GUI something like that shown by the figure.#include <X11/Intrinsic.h> #include <X11/StringDefs.h> #include <Xm/Xm.h> #include <Xm/PushB.h> #include <Xm/Form.h> #include <Dt/ModLabel.h> ModLabelData *data; /* Callback passed to tsol_lbuild_create() */ void callback_function() { char *title, *userval; char *string = (char *)0; char *string1 = (char *)0; int mode, view; Boolean show; m_label_t *sl_label, *work_sl_label; Position x, y; /* Your application-specific implementation goes here */ printf("OK button called\n"); /* Query settings */ mode = (int)tsol_lbuild_get(data, LBUILD_MODE); title = (String)tsol_lbuild_get(data, LBUILD_TITLE); sl_label = (m_label_t*) tsol_lbuild_get(data, LBUILD_VALUE_SL); work_sl_label = (m_label_t*) tsol_lbuild_get(data, LBUILD_WORK_SL); view = (int)tsol_lbuild_get(data, LBUILD_VIEW); x = (Position ) tsol_lbuild_get(data, LBUILD_X); y = (Position ) tsol_lbuild_get(data, LBUILD_Y); userval = (char *)tsol_lbuild_get(data, LBUILD_USERFIELD); show = (Boolean )tsol_lbuild_get(data, LBUILD_SHOW); label_to_str(sl_label, &string, M_LABEL, LONG_NAMES); label_to_str(work_sl_label, &string1, M_LABEL, LONG_NAMES); printf("Mode = %d, Title = %s, SL = %s, WorkSL = %s, View = %d, ", mode, title, string, string1, view); printf("X = %d, Y = %d, Userval = %s, Show = %d\n", x, y, userval, show); } /* Callback to display dialog box upon button press */ void Show(Widget display, caddr_t client_data, caddr_t call_data) { tsol_lbuild_set(data, LBUILD_SHOW, TRUE, NULL); } main(int argc, char **argv) { Widget form, topLevel, display; Arg args[9]; int i = 0, error, retval; char *sl_string = "CNF"; m_label_t * sl_label; topLevel = XtInitialize(argv[0], "XMcmds1", NULL, 0, &argc, argv); form = XtCreateManagedWidget("form", xmFormWidgetClass, topLevel, NULL, 0); retval = str_to_label(sl_string, &sl_label, MAC_LABEL, L_NO_CORRECTION, NULL); printf("Retval = %d\n", retval); data = tsol_lbuild_create( form, callback_function, LBUILD_MODE, LBUILD_MODE_SL, LBUILD_TITLE, "Building Sensitivity Label", LBUILD_VALUE_SL, sl_label, LBUILD_VIEW, LBUILD_VIEW_EXTERNAL, LBUILD_X, 200, LBUILD_Y, 200, LBUILD_USERFIELD, "/export/home/zelda", LBUILD_SHOW, FALSE, NULL); i = 0; XtSetArg(args[i], XmNtopAttachment, XmATTACH_FORM); i++; XtSetArg(args[i], XmNleftAttachment, XmATTACH_FORM); i++; XtSetArg(args[i], XmNrightAttachment, XmATTACH_FORM); i++; XtSetArg(args[i], XmNbottomAttachment, XmATTACH_FORM); i++; display = XtCreateManagedWidget("Show", xmPushButtonWidgetClass, form, args, i); XtAddCallback(display, XmNactivateCallback, Show,0); XtRealizeWidget(topLevel); XtMainLoop(); tsol_lbuild_destroy(data); }When run, the program produces the following output:OK button called Mode = 12, Title = Building Sensitivity label, Label = CNF, WorkSL = SECRET, View = 1, X = 200, Y = 200, Userval = /export/home/zelda, Show = 1The following sections cover these topics:Label Builder behavior Application-specific functionality for Label Builder Privileged operations and Label Builder tsol_lbuild_create routine Extended Label Builder operations ModLabelData structure Label Builderfunctionality label_encodings fileLabel Builder The Label Builder dialog box prompts the end user for information and generates a valid sensitivity label from the input. Label Builder ensures that a valid label or clearance is built. The labels and clearances are defined in the label_encodings file for the system.Label BuilderUpdate buttonLabel Builder provides default behavior for the OK, Reset, Cancel, and Update buttons. The callback passed to the tsol_lbuild_create routine is mapped to the OK button to provide application-specific behavior.The Update button takes the text the user types in the Update With field and checks that the string is a valid label or clearance as defined in the label_encodings file.If the input is not valid, Label Builder generates an error for the user. If the input is valid, Label Builder updates the text in the Label field and stores the value in the appropriate working label field of the ModLabelData variable that is returned by the tsol_lbuild_create routine. See ModLabelData Structure. When the user clicks OK, the user-built value is handled according to the OK button callback implementation. The Label Settings radio button options enable you to build a sensitivity label or clearance from classifications and compartments. These options also enable you to build an information label from classifications, compartments, and markings. Depending on the mode, one of these buttons might be grayed out. This approach is independent of the keyboard entry and Update button method described in the previous section.Label Builderlabel radio buttonsThe information about the classifications, compartments, and markings is specified in the label_encodings file for the system. The combinations and constraints that are specified in the label_encodings file are enforced by graying out invalid combinations. The Label field is updated and the value is stored in the appropriate working label field of the ModLabelData variable that is returned by the tsol_lbuild_create routine when the user chooses options. The user can build a sensitivity label or a clearance by selecting radio buttons in the classification (CLASS) and compartment (COMPS) lists.When the user clicks OK, the user-built value is handled according to the OK button callback implementation. Label BuilderReset buttonThe Reset button sets the text in the Label field to what its value was when the application started. Label BuilderCancel buttonThe Cancel button exits the application without saving any changes. The Label Builder GUI generates a valid label or clearance. You must also add application-specific callbacks, error handling, and other functionality that is associated with that label or clearance. Label Builderauthorizations Label Builderprivileged tasks authorizationsLabel Builder privileged tasksLabel Builder sys_trans_label privilege privilegessys_trans_label Label Builder shows the user only those classifications and related compartments that are dominated by the workspace sensitivity label. If the executable has the sys_trans_label privilege in its effective set, more classifications and compartments might be shown.Your application-specific implementation for the OK button callback might require privileges.If the user does not have the authorization to upgrade or downgrade labels, the OK and Reset buttons are grayed out. The same is true if the user-built label is out of the user's range. The grayed-out buttons prevent the user from completing the task. No privileges can override these restrictions. Label Buildertsol_lbuild_create routine data typesLabel Builder APIstsol_lbuild_create routine tsol_lbuild_create routinedescription of The tsol_lbuild_create routine accepts any widget, a callback function, and a null-terminated series of name and value pairs. The name represents an operation. The routine returns a variable of type ModLabelData.The following describes the information accepted by the tsol_lbuild_create routine:Widget – Label Builder can build the dialog box from any widget. Callback function – The callback function activates when the OK button is clicked. This callback function provides application-specific behavior. Name and value pairs – The name (left) side of the pair specifies an extended operation (see Extended Label Builder Operations) and the value (right) side specifies the value. In some cases, the value is an enumerated constant. In other cases, you provide a value. The pairs can be specified in any order, but every operation you specify requires a valid value.The return value is a data structure that contains information about the dialog box that was just created. The information comes from the tsol_lbuild_create input parameters and user activities during execution. Label Builder provides default values for some fields where no values have been specified.Use the tsol_lbuild_get routine and the tsol_lbuild_set routine to programmatically access and change the information in these name and value pairs. The data structure is described in ModLabelData Structure.The following shows a sample call to the tsol_lbuild_create routine:data= tsol_lbuild_create(form, callback_function, LBUILD_MODE, LBUILD_MODE_SL, LBUILD_TITLE, "Building a Label", LBUILD_VALUE_SL, sl_label, LBUILD_VIEW, LBUILD_VIEW_EXTERNAL, LBUILD_X, 200, LBUILD_Y, 200, LBUILD_USERFIELD “/export/home/zelda”, LBUILD_SHOW, FALSE, NULL); extended operations operations, extendedLBUILD_CHECK_AR operation This section describes the extended operations and valid values that you can pass to the tsol_lbuild_create, tsol_lbuild_get, and tsol_lbuild_set routines. The values that are passed to tsol_lbuild_create are stored in its return value. The return value is of type ModLabelData. The values returned in the parameters can be accessed by calls to tsol_lbuild_get and tsol_lbuild_set. The ModLabelData structure is described in ModLabelData Structure. See the tsol_lbuild_create3TSOL, tsol_lbuild_get3TSOL, and tsol_lbuild_set3TSOL man pages.All extended operations are valid to pass to tsol_lbuild_get. However, the LBUILD_WORK_SL and LBUILD_WORK_CLR operations are not valid to pass to tsol_lbuild_set or tsol_lbuild_create because these values are set by Label Builder based on user input. These exceptions are noted in the following operation descriptions:LBUILD_MODE operationLBUILD_MODE – You can instruct tsol_lbuild_create to create a user interface to build sensitivity labels or clearances. The default value is LBUILD_MODE_SL.LBUILD_MODE_SL valueLBUILD_MODE_SL – Builds a sensitivity label. LBUILD_MODE_CLR valueLBUILD_MODE_CLR – Builds a clearance. LBUILD_VALUE_SL operationLBUILD_VALUE_SL – The starting sensitivity label that is shown in the Label field when the mode is LBUILD_MODE_SL. The default value is ADMIN_LOW. LBUILD_VALUE_CLR operationLBUILD_VALUE_CLR – The starting clearance that is shown in the Label field when the mode is LBUILD_MODE_CLR. The default value is ADMIN_LOW. LBUILD_USERFIELD operationLBUILD_USERFIELD – A character string prompt that appears at the top of the Label Builder dialog box. The default value is NULL. LBUILD_SHOW operationLBUILD_SHOW – Shows or hides the Label Builder dialog box. The default value is FALSE.TRUE – Shows the Label Builder dialog box. FALSE – Hides the Label Builder dialog box. LBUILD_TITLE operationLBUILD_TITLE – A character string title that appears at the top of the Label Builder dialog box. The default value is NULL. LBUILD_WORK_SL operationLBUILD_WORK_SL – The sensitivity label that the user is building. This value is updated based on the user's input when the user selects the Update button or interactively chooses an option. The default value is ADMIN_LOW and is not a valid extended operation for tsol_lbuild_set or tsol_lbuild_create. LBUILD_WORK_CLR operationLBUILD_WORK_CLR – The clearance that the user is building. This value is updated based on the user's input when the user selects the Update button or interactively chooses an option. The default value is ADMIN_LOW and is not a valid extended operation for tsol_lbuild_set or tsol_lbuild_create. LBUILD_X operationLBUILD_X – The X offset in pixels from the upper left corner of the Label Builder dialog box in relation to the upper left corner of the screen. By default, the Label Builder dialog box is positioned in the middle of the screen. LBUILD_Y operationLBUILD_Y – The Y offset in pixels from the upper left corner of the Label Builder dialog box in relation to the upper left corner of the screen. By default, the Label Builder dialog box is positioned in the middle of the screen. privilegessys_trans_labelLBUILD_UPPER_BOUND operationLBUILD_UPPER_BOUND – The highest classification, and related compartments and markings, that are available to the user as radio buttons. These buttons are used to interactively build a label or a clearance. A value you supply must be within the user's range. If no value is supplied, this value is the user's workspace sensitivity label. Or, if the executable has the sys_trans_label privilege, this value is the user's clearance. LBUILD_LOWER_BOUND operationLBUILD_LOWER_BOUND – The lowest classification, and related compartments and markings, that are available to the user as radio buttons. These buttons are used to interactively build a label or a clearance. This value is the user's minimum label. If no value is specified, the value is based on the default specified by the user's attributes. LBUILD_CHECK_AR operationLBUILD_CHECK_AR – Checks whether the user-built label is within the user's range. A value of 1 means “check,” and a value of 0 means “do not check.” If the label is out of range, an error message is displayed to the user. The default value is 1. LBUILD_VIEW operationLBUILD_VIEW – Determines whether to use the internal or the external label representation. The default value is LBUILD_VIEW_EXTERNAL.LBUILD_VIEW_INTERNAL valueLBUILD_VIEW_INTERNAL – Uses the internal names for the highest and lowest labels in the system, ADMIN_HIGH and ADMIN_LOW. LBUILD_VIEW_EXTERNAL valueLBUILD_VIEW_EXTERNAL – Promotes an ADMIN_LOW label to the next lowest label and demotes an ADMIN_HIGH label to the next highest label. Label BuilderModLabelData structure data typesLabel Builder APIsModLabelData structure ModLabelData structure Motif applicationLabel Builder widgets The ModLabelData structure contains information about the state of the Label Builder interface that is created by the call to the tsol_lbuild_create routine. The following table describes the ModLabelData fields. All fields, except for the widgets and the callbacks, are accessible by specifying the associated extended operation and a valid value in a call to tsol_lbuild_set or tsol_lbuild_get. For descriptions of the extended operations, see Extended Label Builder Operations.Extended Operation or Description Data Type Field Comments LBUILD_CHECK_AR int check_ar LBUILD_MODE int mode LBUILD_SHOW Bool show LBUILD_TITLE char *lbuild_title LBUILD_UPPER_BOUND, LBUILD_LOWER_BOUND brange_t range LBUILD_USERFIELD char *userfield LBUILD_VALUE_CLR bclear_t *clr LBUILD_VALUE_SL m_label_t *sl LBUILD_VIEW int view LBUILD_WORK_CLR bclear_t *clr_work Not valid for tsol_lbuild_set or tsol_lbuild_create LBUILD_WORK_SL m_label_t *sl_work Not valid for tsol_lbuild_set or tsol_lbuild_create LBUILD_X Position x LBUILD_Y Position y Callback passed to tsol_lbuild_create void (*event_handler) Cancel button Widget cancel Help button Widget help Label Builder dialog box Widget lbuild_dialog OK button Widget ok Reset button Widget reset Update button Widget update Motif applicationonline help online helpLabel Builder Label Builderonline help The Help button and other widgets that are used in the user interface can be accessed directly from your application code through the lbl_shell field in the ModLabelData structure. To add online help to your application, follow the procedures and guidelines in the Common Desktop Environment: Help System Author's and Programmer's Guide.