| Previous | Contents | Index |
The following sections describe differences from and issues in the standard ICE implementation provided with X11R6.6.
Connection and Protocol Authentication
The implementation of ICE included with DECwindows Motif for OpenVMS Alpha Version 1.3 does not include any authentication mechanisms for ICE connections. All listen objects must use IceSetHostBasedAuthProc to register host-based authentication.
For protocol authentication, all authentication schemes provided when the protocol is registered are permitted. This differs from the standard ICE implementation, where only those those schemes defined in the ICE Authority (IceAuth) file are allowed.
The sample implementation of ICE provided by X.Org contained objects whose name differed from that described in the ICE specification. The following table lists those objects and specifies which name was used in the DECwindows Motif for OpenVMS Alpha Version 1.3 implementation of ICE.
| Documented Object Name | Implemented Object Name |
|---|---|
| IceGetContext | IceConnectionGetContext |
| major_opcode | majorOpcode |
| minor_opcode | minorOpcode |
The header structure used with IceGetHeaderExtra must have a sizeof
value that is a multiple of 8 bytes.
4.5.4 X Session Management Protocol (XSMP) Support
V1.3
The X Session Management Protocol (XSMP) provides a standard way for users to save client sessions. Each session is controlled by a network service known as the session manager. The session manager issues commands that direct client applications to save their state information for use during subsequent sessions.
This protocol is built on top of ICE, which manages the client connections to the session manager server.
Code that uses XSMP must include the following header files:
# include "DECW$INCLUDE:SM.h" # include "DECW$INCLUDE:SMlib.h" # include "DECW$INCLUDE:SMproto.h" |
The following sections describe the implementation of XSMP provided
with DECwindows Motif for OpenVMS Alpha Version 1.3, highlighting any variances from or restrictions
posed by the standard implementation. For a detailed description of the
XSMP protocol and the available server requests, see the X Window
System (Scheifler and Gettys) series of manuals published by
Butterworth-Heinemann, or visit the X.Org web site (http://www.x.org)
for the X Window System protocol and library specifications.
4.5.4.1 Multithreading Considerations
The implementation of XSMP is thread safe, using locks on the underlying ICE connection as needed. All send message operations are thread cancellation points; all callback operations are made by locking the associated ICE connection.
When SmcOpenConnection is called, it opens an ICE connection and
processes messages until the session manager registers the client. The
open connection subsequently causes a series of ICE watch procedures to
be called. Typically, these procedures add the connection to a list
monitored for input. IceProcessMessages is called when input to the
list arrives. The thread issuing the IceProcessMessages calls will be
blocked if it tries to handle a new connection.
4.5.4.2 Differences from the Standard Implementation
The following sections describe differences from and issues in the standard XSMP implementation provided with X11R6.6.
SmcCloseConnection and SmsCleanUp
In the standard implementation, SmcCloseConnection disables shutdown negotiation for an ICE connection, which results in abrupt termination of the connection. This can prevent the session manager from receiving all SmCloseConnection messages.
In the DECwindows Motif implementation, shutdown negotiation is enabled. SmcCloseConnection returns SmcClosedASAP, and the connection is closed only after the session manager calls SmsCleanUp.
Note also that the sample session manager code does not specify whether SmsCleanUp closes an ICE Connection. In the DECwindows Motif implementation, an IceCloseConnection call is issued.
POSIX Property Names and Data Type Definitions
The standard specification defines the data types and property names
supported for POSIX. The DECwindows Motif implementation specifies the
property names; however, the data types definitions are not provided,
since they may vary based on the use of session manager in the OpenVMS
Alpha environment.
4.5.5 MIT Shared Memory Extension (MIT-SHM) Support
V1.2
On OpenVMS Alpha systems, shared memory extension support provides the capability to share memory XImages. This is a version of the XImage interface where the actual image data is stored in a shared-memory segment. Consequently, the image does not need to be moved through the Xlib interprocess communication channel. For large images, use of this extension can result in dramatic performance increases.
Support for shared memory pixmaps is also provided. Shared memory pixmaps are two-dimensional arrays of pixels in a format specified by the X server, where the image data is stored in the shared memory segment. Through the use of shared memory pixmaps, you can change the contents of these pixmaps without using any Xlib routines.
These routines are included in the client side extension library. See
Section 4.3.8 for details on linking this library.
4.5.5.1 How to Use Shared Memory Extension
Code that uses the shared memory extension must include the following header files:
# include "DECW$INCLUDE:Xlib.h" # include "DECW$INCLUDE:shm.h" # include "DECW$INCLUDE:XShm.h" |
Any code that uses the shared memory extension should first check that the server provides the extension. In some cases, such as running over the network, the extension does not work.
To check if the shared memory extension is available on your system, call one of the following routines:
Status XShmQueryExtension (display)
Display *display
|
Status XShmQueryVersion (display, major, minor, pixmaps)
Display *display;
int *major, *minor;
Bool *pixmaps
|
The following table lists each argument and its description.
| Argument | Description |
|---|---|
| display |
The current display.
If the shared memory extension is used, the return value from either function is True. Otherwise, your program operates using conventional Xlib calls. |
| major | Major version number of the extension implementation. Returned by XShmQueryVersion. |
| minor | Minor version number of the extension implementation. Returned by XShmQueryVersion. |
| pixmaps | True, indicates that shared memory pixmaps are supported. |
The following sequence shows the process for creating and using shared memory XImages:
The following sections explain each step in this process:
Step 1---Creating a Shared Memory XImage Structure
To create a shared memory XImage, use the XShmCreateImage routine, which has the following format:
XImage *XShmCreateImage (display, visual, depth, format, data,
shminfo, width, height)
Display *display;
Visual *visual;
unsigned int depth, width, height;
int format;
char *data;
XShmSegmentInfo *shminfo;
|
Most of the arguments are the same as for XCreateImage (See the X Window System for a description of the XCreateImage routine.) Note that there are no offset, bitmap_pad, or bytes_per_line arguments. These quantities are set by the server, and your code needs to abide by them. Unless you have already allocated the shared memory segment (see step 2), you pass in NULL for the data pointer.
The argument shminfo is a pointer to a structure of type XShmSegmentInfo. Allocate one of these structures so that it has a lifetime at least as long as that of the shared memory XImage. There is no need to initialize this structure before the call to XShmCreateImage.
If successful, an XImage structure is returned, which you can use for the subsequent steps.
Step 2---Creating the Shared Memory Segment
Create the shared memory segment after the creation of the XImage because the XImage returns information that indicates how much memory to allocate.
The following example illustrates how to create the segment:
shminfo.shmid = shmget (IPC_PRIVATE,
image->bytes_per_line * image->height, IPC_CREAT|0777);
|
This example assumes that you called your shared memory XImage structure. A return value of 0 indicates the shared memory allocation has failed. Use the bytes_per_line field, not the width you used to create the XImage, as they may be different.
Note that the shared memory ID returned by the system is stored in the shminfo structure. The server needs that ID to attach itself to the segment.
Step 3---Attaching the Shared Memory Segment
Attach the shared memory segment to your process as in the following example:
shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0); |
The address returned by shmat is stored in both the XImage structure and the shminfo structure.
To finish supplying arguments in the shminfo structure, decide how you want the server to attach to the shared memory segment, and set the shminfo.readOnly field as follows:
shminfo.readOnly = False; |
If you set the structure to True, the server cannot write to this segment, and XShmGetImage calls fail.
The shared memory segment routines are provided with DECwindows Motif. Using global sections, these routines emulate the shared memory routines on UNIX systems. |
Step 4---Informing the Server About the Shared Memory Segment
Tell the server to attach to your shared memory segment as in the following example:
Status XShmAttach (display, shminfo); |
If successful, a nonzero status is returned, and your XImage is ready for use.
Step 5---Using the Shared Memory XImage
To write a shared memory XImage into an X drawable, use the XShmPutImage routine. The XShmPutImage routine uses the following format:
XShmPutImage (display, d, gc, image, src_x, src_y,
dest_x, dest_y, width, height, send_event)
Display *display;
Drawable d;
GC gc;
XImage *image;
int src_x, src_y, dest_x, dest_y;
unsigned int width, height;
Bool send_event;
|
The interface is identical to the XPutImage routine (see the X Window System), except for one additional parameter, send_event. If this parameter is passed as True, the server generates a completion event when the image write is complete. This allows your program to know when it is safe to begin manipulating the shared memory segment again.
The completion event is of the type XShmCompletionEvent, which is defined as follows:
typedef struct {
inttype; /* of event */
unsigned long serial; /* # of last request processed */
Bool send_event; /* true if came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable drawable; /* drawable of request */
int major_code; /* ShmReqCode */
int minor_code; /* X_ShmPutImage */
ShmSeg shmseg; /* the ShmSeg used in the request */
unsigned long offset; /* the offset into ShmSeg used */
} XShmCompletionEvent;
|
To determine the event type value that is used at run time, use the XShmGetEventBase routine as in the following example:
int CompletionType = XShmGetEventBase (display) + ShmCompletion;
|
If you modify the shared memory segment before the arrival of the completion event, the results may be inconsistent. |
To read image data into a shared memory XImage, use the XShmGetImage routine, which uses the following format:
Status XShmGetImage (display, d, image, x, y, plane_mask)
Display *display;
Drawable d;
XImage *image;
int x, y;
unsigned long plane_mask;
|
The following table lists each argument and its description.
| Argument | Description |
|---|---|
| display | The display of interest. |
| d | The source drawable. |
| image | The destination XImage. |
| x | X-offset within the source drawable. |
| y | Y-offset within the source drawable. |
| plane_mask | The planes that are to be read. |
To destroy a shared memory XImage, first instruct the server to detach from it, then destroy the segment itself. The following example illustrates how to destroy a shared memory XImage:
XShmDetach (display, shminfo); XDestroyImage (image); shmdt (shminfo.shmaddr); shmctl (shminfo.shmid, IPC_RMID, 0); |
Unlike X images, for which any image format is usable, the shared memory extension supports only a single format for the data stored in a shared memory pixmap (XYPixmap or ZPixmap). This format is independent of the depth of the image and independent of the screen. (For 1-bit pixmaps the format is irrelevant.)
The XShmPixmapFormat routine returns the shared memory pixmap format for the server. The XShmPixmapFormat routine has the following format:
int XShmPixmapFormat (display)
Display *display;
|
Your application can only use shared memory pixmaps in the format returned by the XShmPixmapFormat routine (including bits-per-pixel). To create a shared memory pixmap do the following:
Pixmap XShmCreatePixmap (display, d, data, shminfo, width,
height, depth);
Display *display;
Drawable d;
char *data;
XShmSegmentInfo *shminfo;
unsigned int width, height, depth;
|
Starting with DECwindows Motif for OpenVMS Version 1.1, DECwindows Motif supports the X Image Extension (XIE). XIE allows image display processing using resources on the server side of the X client-server model. XIE eliminates the need to transmit image data repeatedly from the client to the server and also allows data to be transmitted in compressed form, reducing the network load.
DECwindows Motif includes the XIE client side shareable library (XIE$SHRLIB.EXE) and C language header files. These allow applications to communicate with any X11 server that supports the XIE extension.
An XIE program uses a structure called the XIEImage to describe image data on the client side. This general mechanism describes data that the destination server is incapable of processing. Consult the documentation for the server system for information on what data types and sizes are supported. Unless the documentation specifies different limits, the server is capable of processing unsigned byte (UdpK_DTypeBU), unaligned bit field (UdpK_DTypeVU), and aligned bit field (UdpK_DTypeV) data, with a maximum depth of 8 bits per pixel per component. The XIE client library supports these data types, as well as unsigned word (UdpK_DTypeWU), and a depth of up to 16 bits per pixel per component.
Although the XIE protocol and programming interface have been
standardized for X11R6, DECwindows Motif has not yet migrated to the
latest implementation of this protocol.
4.6 DECwindows Extensions to Motif
The following sections describe features related to DECwindows
extensions to the X Window System.
4.6.1 SVN Widget Supports Extended Selection
The Structured Visual Navigation (SVN) widget now allows users to
extend a range of selection using the Shift+Down-Arrow key sequence.
Note that this change has also been applied to the sample program
SVNMSAMPLE.C.
4.6.2 DXmCSText Input Method Support
X11R5 input method support was added to the DXmCSText widget. Specify
input methods using the vendor shell XmNinputMethod resource. However,
to maintain backward compatibility, the existing input method resources
DXmNinputMethod and DXmNinputMethodType are still available.
4.7 Application Programming
The following sections describe features related to application
programming.
4.7.1 Drag-and-Drop Enabled Widgets
V1.2
The drag-and-drop feature lets you move or copy information between widgets. This feature is provided primarily for programmers to incorporate the feature into their applications.
All DECwindows Motif for OpenVMS Version 1.2 and higher applications support the drag-and-drop feature, with the exception of Notepad. DECwindows Mail supports drag-and-drop in all windows except the main message area, where DECwindows Mail has its own drag-and-drop feature; you can use MB2 to move messages around with the SVN interface.
Drag-and-drop functionality has been implemented in the widgets listed in Table 4-11.
| Widget | Drag Operation | Drop Operation |
|---|---|---|
| XmText | copy and move | copy and move |
| XmTextField | copy and move | copy and move |
| XmLabel | copy | |
| XmPushButton | copy | |
| XmToggleButton | copy | |
| XmList | copy |
For information about how to include additional drag-and-drop
functionality in applications and for an example of a drag-and-drop
program, see the Open Software Foundation: OSF/Motif Programmer's
Guide, Revision 1.2 manual.
4.7.2 CDA Programming
This section describes features and changes related to CDA programming.
4.7.2.1 Changes to the CDA Programming Interface
V1.2
This section describes the changes to the programming interface for this version of CDA Run-Time Services.
This version provides a new set of header files that define CDA constants, types, and routines using portable naming conventions. By using these new naming conventions, you can use a wider variety of C compilers to minimize the amount of system-specific code in your CDA applications.
The names of the new set of header files are the same as the names of the previous set of header files, except that the dollar sign ($) has been removed. For example, the cda$msg.h include file is now called cdamsg.h. Other examples include the following: The DDIF$K_DSC_MAJOR_VERSION symbol is now declared as DDIF_K_DSC_MAJOR_VERSION, and the CDA$_NORMAL status value is now defined as CDA_NORMAL.
The previous set of header files is also included in this version, but these files will no longer be updated. Changes introduced since the release of DECwindows Motif Version 1.1 (for example, the new definitions for audio support), are available only in the new set of header files. To use the new CDA features, change the file names in your source code.
The new set of header files supplements the previous set of header files. If you want to write ANSI-compliant applications using CDA definitions and CDA Toolkit calls, use the new set of header files. However, you can continue to use the header files that define symbols containing the dollar sign ($) provided you choose a non-ANSI compilation mode.
By using the previous set of header files, you can successfully build existing source code that uses the previous naming conventions.
See Table 4-12 for a list of new header file names.
| Previous Name | New Name |
|---|---|
| cda$def.h | cdadef.h |
| cda$msg.h | cdamsg.h |
| ddif$def.h | ddifdef.h |
| dtif$def.h | dtifdef.h |
| cda$ptp.h | cdaptp.h |
| cda$typ.h | cdatyp.h |
| dvr$msg.h | dvrmsg.h |
| dvr$cc_def.h | dvrccdef.h |
| dvr$cc_ptp.h | dvrccptp.h |
| dvr$decw_def.h | dvrwdef.h |
| dvr$decw_ptp.h | dvrwptp.h |
| Previous | Next | Contents | Index |