XSGIvcSendMonitorCommand(3)

     NAME
          XSGIvcSendMonitorCommand, XSGIvcSendMonitorQuery,
          XSGIvcQueryMonitorBaseProtocol,
          XSGIvcInitMonitorBaseProtocol - Monitor control

     SYNOPSIS
          #include <X11/extensions/XSGIvc.h>

          void XSGIvcSendMonitorCommand(Display *display,
              int screen,
              int channel,
              const char *monitorCommand,
              int commandLength)

          Status XSGIvcSendMonitorQuery(Display *display,
              int screen,
              int channel,
              const char *monitorCommand,
              int commandLength,
              char **monitorResponse,
              int *responseLength)

          int XSGIvcQueryMonitorBaseProtocol(Display *display,
              int screen,
              int channel)

          void XSGIvcInitMonitorBaseProtocol(Display *display,
              int screen,
              int channel)

     PARAMETERS
          display        Specifies the connection to the X server.

          screen         Specifies the screen of the X server.

          channel        Specifies the channel number.

          monitorCommand The command to be sent to the monitor.  The
                         command sequence must be a valid command
                         packet that will be sent unprocessed to the
                         monitor connected to channel.

          commandLength  The length, in bytes, of monitorCommand.

          monitorResponse
                         Returns a pointer to a buffer containing the
                         response returned from the monitor. This
                         response will be returned unprocessed.

          responseLength The length, in bytes, of monitorResponse.

     DESCRIPTION
          These functions allow an application program to communicate
          with a monitor that has the capability to send and receive
          such commands.  Client programs are responsible for
          composing monitor commands and for parsing the result; the X
          server simply transports strings between the client and
          monitor.

          This function is intended for server-to-monitor
          communications.  Servers do not guarantee that other devices
          connected to the bus will function properly, nor will the
          bus connecting a monitor always be active; spontaneous
          messages from monitors or other devices can be ignored.


        Functions
          XSGIvcSendMonitorCommand sends a command - for which no
          response is expected - to the monitor of the specified
          channel.

          If a response is expected, use XSGIvcSendMonitorQuery which
          sends a command to the monitor of the specified channel and
          waits for a response before continuing.  The response is
          placed in a buffer whose address is returned in
          monitorResponse.  The client is responsible for calling
          XFree on the memory allocated by the library.

          The XSGIvcInitMonitorBaseProtocol function must be called to
          initialize the protocol the server is going to use to
          communicate with the monitor before any commands or queries
          are sent to the monitor. This function reinitializes the
          monitor protocol each time it is called, and may be called
          at any time. XSGIvcQueryMonitorBaseProtocol may be called to
          find out if the protocol has already been initialized (see
          below).

          The XSGIvcQueryMonitorBaseProtocol function returns a
          description of the protocol the X-Server will use to
          communicate with the monitor.  The following are defined:

          XSGIVC_MBPUninitialized
                                The protocol between the server and
                                the monitor has not yet been
                                initialized. Implies that the client
                                must first call
                                XSGIvcInitMonitorBaseProtocol in order
                                to get a valid response.

          XSGIVC_MBPNone        The server or monitor does not support
                                monitor commands on this channel.

          XSGIVC_MBPAccessBus   The server will use ACCESS.bus
                                communications protocol. The content
                                of message buffers referenced by
                                monitorCommand and monitorResponse
                                begin with ACCESS.bus primary opcode.
                                During its initialization, the server
                                will switch connected monitors from
                                VESA DDC1/2AB to ACCESS.bus
                                communications mode.


     EVENTS
          No events.



     RETURNED VALUE
          A BadAccess error indicates a breakdown in the monitor
          protocol, and that the client must call
          XSGIvcInitMonitorBaseProtocol in order to re-establish
          communications with the monitor.  In addition, a BadAccess
          error will result from a send monitor command or query call
          when XSGIvcQueryMonitorBaseProtocol has returned
          XSGIVC_MBPNone.

          For XSGIvcQueryMonitorBaseProtocol, see the discussion in
          DESCRIPTION.


     SEE ALSO
          XSGIvc