Messages
========

The (ssh message) module provides procedures for handling of Guile-SSH messages.

Messages Handling
-----------------

A message is an object that represents a single request to a Guile-SSH server.  Basically the server handles requests in some loop in which it accepts messages with server-message-get procedure (see Servers), handles the received request and replies to the message.

 -- Scheme Procedure: message? x
     Return #t if X a Guile-SSH message, #f otherwise.

 -- Scheme Procedure: message-reply-default message
     Reply with SSH_MSG_UNIMPLEMENTED.  Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-reply-success message [args]
     Reply ``success'' to the MESSAGE.  This procedure is a convenient wrapper for other *-reply-success procedures (see below).  The right procedure to use will be selected depending on a type of the message.  The procedure may take additional argument 'partial for that changes reply to authentication request, and a bound-port for a global request.

     Throw an exception on error.  Return value is undefined.

 -- Scheme Procedure: message-service-reply-success message
     Reply with ``success'' status on the service-request MESSAGE. Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-auth-reply-success message partial?
     Reply with ``success'' on the auth-request MESSAGE.  Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-channel-request-reply-success message
     Reply ``success'' on a channel-request MESSAGE. Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-global-request-reply-success message bound-port
     Reply ``success'' on a global request MESSAGE.  Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-auth-reply-public-key-ok message
     Reply ``OK'' on the public key auth-request MESSAGE.  Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-channel-request-open-reply-accept message
     Accept open-channel request.  Return a new Guile-SSH channel, or #f on error.

 -- Scheme Procedure: message-get-type message
     Get type of the MESSAGE in the following format:

          <msg-type> = "'(" <type> [<WSP> <subtype>] ")"

     The procedure returns #f on error.

     Example:

          (message-get-type msg)
          => '(request-auth auth-method-none)

     Possible types:

     request-auth
          Subtypes:

          auth-method-unknown

          auth-method-none

          auth-method-password

          auth-method-publickey

          auth-method-hostbased

          auth-method-interactive

     request-channel-open
          Subtypes:

          channel-unknown

          channel-session

          channel-direct-tcpip

          channel-forwarded-tcpip

          channel-x11

     request-channel
          Subtypes:

          channel-request-unknown

          channel-request-pty

          channel-request-exec

          channel-request-shell

          channel-request-env

          channel-request-subsystem

          channel-request-window-change

     request-service

     request-global
          Subtypes:

          global-request-unknown

          global-request-tcpip-forward

          global-request-cancel-tcpip-forward

 -- Scheme Procedure: message-get-req message
     Get a request object from the MESSAGE.  Returns a new request object (see Parsing of Requests).  Throw guile-ssh-error on error.

 -- Scheme Procedure: message-auth-set-methods! message methods-list
     Set authentication methods to METHODS-LIST.  Possible methods are: password, public-key, interactive, host-based.  Throw guile-ssh-error on error.  Return value is undefined.

 -- Scheme Procedure: message-get-session message
     Get the session from which the MESSAGE was received.  Return the session.

Parsing of Requests
-------------------

 -- Scheme Procedure: service-req:service request
     Get service name from a service REQUEST.

 -- Scheme Procedure: channel-open-req:orig request
 -- Scheme Procedure: channel-open-req:orig-port request
 -- Scheme Procedure: channel-open-req:dest request
 -- Scheme Procedure: channel-open-req:dest-port request
     Get originator, originator-port, destination and destination-port from the channel-open REQUEST.

 -- Scheme Procedure: auth-req:user request
 -- Scheme Procedure: auth-req:password request
 -- Scheme Procedure: auth-req:pubkey request
 -- Scheme Procedure: auth-req:pubkey-state request
     Get user, password, public key and public key state from the auth REQUEST.

 -- Scheme Procedure: pty-req:term request
 -- Scheme Procedure: pty-req:width request
 -- Scheme Procedure: pty-req:height request
 -- Scheme Procedure: pty-req:pxwidth request
 -- Scheme Procedure: pty-req:pxheight request
     Get terminal, terminal width, terminal height, terminal pxwidth and terminal pxheight from the PTY REQUEST.

 -- Scheme Procedure: env-req:name request
 -- Scheme Procedure: env-req:value request
     Get environment variable name and its value from the environment REQUEST.

 -- Scheme Procedure: exec-req:cmd request
     Get a command from the exec REQUEST.

 -- Scheme Procedure: global-req:addr request
 -- Scheme Procedure: global-req:port request
     Get address and port from the global REQUEST.