PEXInitialize(3) — Subroutines

Name

PEXInitialize - Initialize PEXlib display connection

Synopsis

int PEXInitialize(Display ∗display, PEXExtensionInfo ∗∗info_return, int length, char ∗error_string)

Arguments

displayA pointer to a display structure returned by a successful XOpenDisplay call.

info_returnReturns a pointer to the extension information; if available (see the Description).

lengthThe length, in bytes, of the memory allocated for the error string.

error_stringA pointer to memory allocated for the error string.

Returns

Zero if successful; otherwise, one of the following return values:

PEXBadExtension
PEXBadProtocolVersion
PEXBadFloatConversion
PEXBadLocalAlloc

Description

PEXInitialize initializes PEXlib for the specified display.

PEXInitialize can be called multiple times; subsequent calls will result in the same return value as the first call.

Standard PEXInitialize failure return values are:

PEXBadExtension - the PEX server extension does not exist,
PEXBadProtocolVersion - the PEX server extension does not support a compatible protocol version,
PEXBadFloatConversion - the PEX server extension does not support a protocol floating point format compatible with PEXlib’s native format or a format to which PEXlib supports conversion, or
PEXBadLocalAlloc - PEXlib client-side allocation failed.

If PEXInitialize is successful (return value is zero), or if the return value is PEXBadProtocolVersion, a pointer to the extension information is returned in info_return. Otherwise, a NULL pointer is returned in info_return. The extension information is private to PEXlib and must not be modified or freed by the application.

The error string parameter specifies an address to memory allocated by the application. The constant PEXErrorStringLength is defined as a guideline for the size to allocate for the error string. If no failure occurred, the memory addressed by the error string parameter will be unchanged. If a failure does occur, an error string giving further information about the failure will be copied into this memory (up to the maximum specified by the length parameter).

The actual string returned is implementation dependent, and is provided primarily for convenience in printing an error message for the application’s end-user.

Data Structures

typedef struct {
    unsigned short      major_version;
    unsigned short      minor_version;
    unsigned long       release;
    unsigned long       subset_info;
    char                ∗vendor_name;
    int                 major_opcode;
    int                 first_event;
    int                 first_error;
} PEXExtensionInfo;

Errors

None

Museum