PEXInitialize - Initialize PEXlib display connection (5.0)

Synopsis

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

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
info_return: Returns a pointer to the extension information; if available. (see the Description)
length: The length, in bytes, of the memory allocated for the error string.
error_string: A pointer to memory allocated for the error string.

Returns

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

PEXBadExtension: The PEX extension does not exist.
PEXBadProtocolVersion: The PEX extension does not support a compatible protocol version, where the major protocol version numbers are equal.
PEXBadFloatConversion: The PEX extension does not support a protocol floating- point format compatible with PEXlib's native format or a format to which PEXlib supports conversion.
PEXBadLocalAlloc: PEXlib client-side allocation failed.

Description

Invoke PEXInitialize to initialize PEXlib for the specified display.

You can invoke this function multiple times; subsequent invocations result in the same return value as the first invocation.

If PEXInitialize is successful (return value is zero), or if the implementation issues a return value of PEXBadProtocolVersion, then this function returns a pointer to the extension information in info_return. Otherwise, this function returns a NULL pointer in info_return. Your application must not modify or free the extension information. See the PEXGetExtensionInfo for an explanation of the info_return argument.

The error_string argument specifies a pointer to memory allocated by the application. PEXlib defines the constant PEXErrorStringLength as a guideline for the size your application should allocate for the error string. If no failure occurs, then PEXlib does not change the memory addressed by the error_string argument. If a failure does occur, then PEXlib copies an error string giving further information about the failure into this memory (up to the maximum specified by the length argument).

The actual string returned is implementation-dependent, and PEXlib provides it for convenience in printing an error message for your application's end-user.

Errors