File: gpgme.info,  Node: Miscellaneous UI Server Commands,  Prev: UI Server Checksum Files,  Up: UI Server Protocol

A.10 Miscellaneous UI Server Commands
=====================================

The server needs to implement the following commands which are not
related to a specific command:

 -- Command: GETINFO WHAT
     This is a multi purpose command, commonly used to return a variety
     of information.  The required subcommands as described by the WHAT
     parameter are:

     ‘pid’
          Return the process id of the server in decimal notation using
          an Assuan data line.

To allow the server to pop up the windows in the correct relation to the
client, the client is advised to tell the server by sending the option:

 -- Command option: window-id NUMBER
     The NUMBER represents the native window ID of the clients current
     window.  On Windows systems this is a windows handle (‘HWND’) and
     on X11 systems it is the ‘X Window ID’.  The number needs to be
     given as a hexadecimal value so that it is easier to convey pointer
     values (e.g.  ‘HWND’).

A client may want to fire up the certificate manager of the server.  To
do this it uses the Assuan command:

 -- Command: START_KEYMANAGER
     The server shall pop up the main window of the key manager (aka
     certificate manager).  The client expects that the key manager is
     brought into the foregound and that this command immediately
     returns (does not wait until the key manager has been fully brought
     up).

A client may want to fire up the configuration dialog of the server.  To
do this it uses the Assuan command:

 -- Command: START_CONFDIALOG
     The server shall pop up its configuration dialog.  The client
     expects that this dialog is brought into the foregound and that
     this command immediately returns (i.e.  it does not wait until the
     dialog has been fully brought up).

When doing an operation on a mail, it is useful to let the server know
the address of the sender:

 -- Command: SENDER [--info] [--protocol=NAME] EMAIL
     EMAIL is the plain ASCII encoded address ("addr-spec" as per
     RFC-2822) enclosed in angle brackets.  The address set with this
     command is valid until a successful completion of the operation or
     until a ‘RESET’ command.  A second command overrides the effect of
     the first one; if EMAIL is not given and ‘--info’ is not used, the
     server shall use the default signing key.

     If option ‘--info’ is not given, the server shall also suggest a
     protocol to use for signing.  The client may use this suggested
     protocol on its own discretion.  The same status line as with
     PREP_ENCRYPT is used for this.

     The option ‘--protocol’ may be used to give the server a hint on
     which signing protocol should be preferred.

To allow the UI-server to visually identify a running operation or to
associate operations the server MAY support the command:

 -- Command: SESSION NUMBER [STRING]
     The NUMBER is an arbitrary value, a server may use to associate
     simultaneous running sessions.  It is a 32 bit unsigned integer
     with ‘0’ as a special value indicating that no session association
     shall be done.

     If STRING is given, the server may use this as the title of a
     window or, in the case of an email operation, to extract the
     sender’s address.  The string may contain spaces; thus no
     plus-escaping is used.

     This command may be used at any time and overrides the effect of
     the last command.  A ‘RESET’ undoes the effect of this command.