'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LABELBUILDER 3TSOL "Jul 20, 2007"
.SH NAME
labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set,
tsol_lbuild_destroy \- create a Motif-based user interface for interactively
building a valid label or clearance
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR \fB-lDtTsol\fR [\fIlibrary\fR...]
.fi

.LP
.nf
#include <Dt/ModLabel.h>

\fBModLabelData *tsol_lbuild_create\fR(\fBWidget\fR \fIwidget\fR,
     void \fI(*event_handler)\fR() \fIok_callback\fR,
     \fBlbuild_attributes\fR \fIextended_operation\fR, ..., \fBNULL\fR);
.fi

.LP
.nf
\fBvoid *tsol_lbuild_get\fR(\fBModLabelData *\fR\fIdata\fR,
     \fBlbuild_attributes\fR \fIextended_operation\fR);
.fi

.LP
.nf
\fBvoid tsol_lbuild_set\fR(\fBModLabelData *\fR\fIdata\fR,
     \fBlbuild_attributes\fR \fIextended_operation\fR, ..., \fBNULL\fR);
.fi

.LP
.nf
\fBvoid tsol_lbuild_destroy\fR(\fBModLabelData *\fR\fIdata\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The label builder user interface prompts the end user for information and
generates a valid sensitivity label or clearance from the user input based on
specifications in the \fBlabel_encodings\fR(4) file on the system where the
application runs. The end user can build the label or clearance by typing a
text value or by interactively choosing options.
.sp
.LP
Application-specific functionality is implemented in the callback for the OK
pushbutton. This callback is passed to the \fBtsol_lbuild_create()\fR call
where it is mapped to the OK pushbutton widget.
.sp
.LP
When choosing options, the label builder shows the user only those
classifications (and related compartments and markings) dominated by the
workspace sensitivity label unless the executable has the
\fBPRIV_SYS_TRANS_LABEL\fR privilege in its effective set.
.sp
.LP
If the end user does not have the authorization to upgrade or downgrade labels,
or if the user-built label is out of the user's accreditation range, the OK and
Reset pushbuttons are grayed. There are no privileges to override these
restrictions.
.sp
.LP
\fBtsol_lbuild_create()\fR creates the graphical user interface and returns a
pointer variable of type \fBModLabeldata*\fR that contains information on the
user interface. This information is a combination of values passed in the
\fBtsol_lbuild_create()\fR input parameter list, default values for information
not provided, and information on the widgets used by the label builder to
create the user interface. All information except the widget information should
be accessed with the \fBtsol_lbuild_get()\fR and \fBtsol_lbuild_set()\fR
routines.
.sp
.LP
The widget information is accessed directly by referencing the following fields
of the \fBModLabelData\fR structure.
.sp
.ne 2
.na
\fB\fBlbuild_dialog\fR\fR
.ad
.RS 17n
The label builder dialog box.
.RE

.sp
.ne 2
.na
\fB\fBok\fR\fR
.ad
.RS 17n
The OK pushbutton.
.RE

.sp
.ne 2
.na
\fB\fBcancel\fR\fR
.ad
.RS 17n
The Cancel pushbutton.
.RE

.sp
.ne 2
.na
\fB\fBreset\fR\fR
.ad
.RS 17n
The Reset pushbutton.
.RE

.sp
.ne 2
.na
\fB\fBhelp\fR\fR
.ad
.RS 17n
The Help pushbutton.
.RE

.sp
.LP
The \fBtsol_lbuild_create()\fR parameter list takes the following values:
.sp
.ne 2
.na
\fBwidget\fR
.ad
.RS 15n
The widget from which the dialog box is created. Any Motif widget can be
passed.
.RE

.sp
.ne 2
.na
\fBok_callback\fR
.ad
.RS 15n
A callback function that implements the behavior of the OK pushbutton on the
dialog box.
.RE

.sp
.ne 2
.na
\fB\fB\&..., NULL\fR\fR
.ad
.RS 15n
A \fINULL\fR terminated list of extended operations and value pairs that define
the characteristics and behavior of the label builder dialog box.
.RE

.sp
.LP
\fBtsol_lbuild_destroy()\fR destroys the \fBModLabelData\fR structure returned
by \fBtsol_lbuild_create()\fR.
.sp
.LP
\fBtsol_lbuild_get()\fR and \fBtsol_lbuild_set()\fR access the information
stored in the \fBModLabelData\fR structure returned by
\fBtsol_lbuild_create()\fR.
.sp
.LP
The following extended operations can be passed to \fBtsol_lbuild_create()\fR
to build the user interface, to \fBtsol_lbuild_get()\fR to retrieve information
on the user interface, and to \fBtsol_lbuild_set()\fR to change the user
interface information. All extended operations are valid for
\fBtsol_lbuild_get()\fR, but the \fB*WORK*\fR operations are not valid for
\fBtsol_lbuild_set()\fR or \fBtsol_lbuild_create()\fR because these values are
set from input supplied by the end user. These exceptions are noted in the
descriptions.
.sp
.ne 2
.na
\fB\fBLBUILD_MODE\fR\fR
.ad
.RS 22n
Create a user interface to build a sensitivity label or a clearance. Value is
\fBLBUILD_MODE_SL\fR by default.
.sp
.ne 2
.na
\fB\fBLBUILD_MODE_SL\fR\fR
.ad
.RS 19n
Build a sensitivity label.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_MODE_CLR\fR\fR
.ad
.RS 19n
Build a clearance.
.RE

.RE

.sp
.ne 2
.na
\fB\fBLBUILD_VALUE_SL\fR\fR
.ad
.RS 22n
The starting sensitivity label. This value is \fBADMIN_LOW\fR by default and is
used when the mode is \fBLBUILD_MODE_SL\fR.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_VALUE_CLR\fR\fR
.ad
.RS 22n
The starting clearance. This value is \fBADMIN_LOW\fR by default and is used
when the mode is \fBLBUILD_MODE_CLR\fR.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_USERFIELD\fR\fR
.ad
.RS 22n
A character string prompt that displays at the top of the label builder dialog
box. Value is \fINULL\fR by default.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_SHOW\fR\fR
.ad
.RS 22n
Show or hide the label builder dialog box. Value is \fBFALSE\fR by default.
.sp
.ne 2
.na
\fB\fBTRUE\fR\fR
.ad
.RS 9n
Show the label builder dialog box.
.RE

.sp
.ne 2
.na
\fB\fBFALSE\fR\fR
.ad
.RS 9n
Hide the label builder dialog box.
.RE

.RE

.sp
.ne 2
.na
\fB\fBLBUILD_TITLE\fR\fR
.ad
.RS 22n
A character string title that appears at the top of the label builder dialog
box. Value is \fINULL\fR by default.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_WORK_SL\fR\fR
.ad
.RS 22n
Not valid for \fBtsol_lbuild_set()\fR or \fBtsol_lbuild_create()\fR. The
sensitivity label the end user is building. Value is updated to the end user's
input when the end user selects the Update pushbutton or interactively chooses
an option.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_WORK_CLR\fR\fR
.ad
.RS 22n
Not valid for \fBtsol_lbuild_set()\fR or \fBtsol_lbuild_create()\fR. The
clearance the end user is building. Value is updated to the end user's input
when the end user selects the Update pushbutton or interactively chooses an
option.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_X\fR\fR
.ad
.RS 22n
The X position in pixels of the top-left corner of the label builder dialog box
in relation to the top-left corner of the screen. By default the label builder
dialog box is positioned in the middle of the screen.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_Y\fR\fR
.ad
.RS 22n
The Y position in pixels of the top-left corner of the label builder dialog box
in relation to the top-left corner of the screen. By default the label builder
dialog box is positioned in the middle of the screen.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_LOWER_BOUND\fR\fR
.ad
.RS 22n
The lowest classification (and related compartments and markings) available to
the user as radio buttons for interactively building a label or clearance. This
value is the user's minimum label.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_UPPER_BOUND\fR\fR
.ad
.RS 22n
The highest classification (and related compartments and markings) available to
the user as radio buttons for interactively building a label or clearance. A
supplied value should be within the user's accreditation range.  If no value is
specified, the value is the user's workspace sensitivity label, or if the
executable has the \fBPRIV_SYS_TRANS_LABEL\fR privilege, the value is the
user's clearance.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_CHECK_AR\fR\fR
.ad
.RS 22n
Check that the user-built label entered in the Update With field is within the
user's accreditation range. A value of 1 means check, and a value of 0 means do
not check. If checking is on and the label is out of range, an error message is
raised to the end user.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_VIEW\fR\fR
.ad
.RS 22n
Use the internal or external label representation. Value is
\fBLBUILD_VIEW_EXTERNAL\fR by default.
.sp
.ne 2
.na
\fB\fBLBUILD_VIEW_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
Use the internal names for the highest and lowest labels in the system:
\fBADMIN_HIGH\fR and \fBADMIN_LOW\fR.
.RE

.sp
.ne 2
.na
\fB\fBLBUILD_VIEW_EXTERNAL\fR\fR
.ad
.sp .6
.RS 4n
Promote an \fBADMIN_LOW\fR label to the next highest label, and demote an
\fBADMIN_HIGH\fR label to the next lowest label.
.RE

.RE

.SH RETURN VALUES
.sp
.LP
The \fBtsol_lbuild_get()\fR function returns \fB\(mi1\fR if it is unable to get
the value.
.sp
.LP
The \fBtsol_lbuild_create()\fR function returns a variable of type
\fBModLabelData\fR that contains the information provided in the
\fBtsol_lbuild_create()\fR input parameter list, default values for information
not provided, and information on the widgets used by the label builder to
create the user interface.
.SH EXAMPLES
.LP
\fBExample 1 \fRCreate a Label Builder.
.sp
.in +2
.nf
(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_SL,
     LBUILD_TITLE, "Setting Sensitivity Label",
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);
.fi
.in -2
.sp

.LP
\fBExample 2 \fRQuery the Mode and Display the Label Builder.
.sp
.LP
These examples call the \fBtsol_lbuild_get()\fR function to query the mode
being used, and call the \fBtsol_lbuild_set()\fR function so the label builder
dialog box displays.

.sp
.in +2
.nf
mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDestroy the ModLabelData Variable.
.sp
.LP
This example destroys the \fBModLabelData\fR variable returned in the call to
\fBtsol_lbuild_create()\fR.

.sp
.in +2
.nf
tsol_lbuild_destroy(lbldata);
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/dt/include/Dt/ModLabel.h\fR\fR
.ad
.sp .6
.RS 4n
Header file for label builder functions
.RE

.sp
.ne 2
.na
\fB\fB/etc/security/tsol/label_encodings\fR\fR
.ad
.sp .6
.RS 4n
The label encodings file contains the classification names, words, constraints,
and values for the defined labels of this system.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibtsol\fR(3LIB), \fBlabel_encodings\fR(4), \fBattributes\fR(5)
.sp
.LP
\fILabel Builder APIs\fR in \fISolaris Trusted Extensions Developer\&'s
Guide\fR
.SH NOTES
.sp
.LP
The functionality described on this manual page is available only if the system
is configured with Trusted Extensions.