guile-ssh/doc/api-messages.texi

@c -*-texinfo-*-
@c This file is part of Guile-SSH Reference Manual.
@c Copyright (C) 2014 Artyom V. Poptsov
@c See the file guile-ssh.texi for copying conditions.

@node Messages
@section Messages

@cindex talking to a SSH client
@tindex message

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

@menu
* Message Handling::
* Parsing of Requests::
@end menu

@node Message Handling
@subsection 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 @code{server-message-get} procedure
(@pxref{Servers}), handles the received request and replies to the
message.

@deffn {Scheme Procedure} message? x
Return @code{#t} if @var{x} a Guile-SSH message, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} message-reply-default message
Reply with @var{SSH_MSG_UNIMPLEMENTED}.  Throw @code{guile-ssh-error}
on error.  Return value is undefined.
@end deffn

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

Throw an exception on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-service-reply-success message
Reply with ``success'' status on the service-request @var{message}.
Throw @code{guile-ssh-error} on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-auth-reply-success message partial?
Reply with ``success'' on the auth-request @var{message}.  Throw
@code{guile-ssh-error} on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-channel-request-reply-success message
Reply ``success'' on a channel-request @var{message}.
Throw @code{guile-ssh-error} on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-global-request-reply-success message bound-port
Reply ``success'' on a global request @var{message}.  Throw
@code{guile-ssh-error} on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-auth-reply-public-key-ok message
Reply ``OK'' on the public key auth-request @var{message}.  Throw
@code{guile-ssh-error} on error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} message-channel-request-open-reply-accept message
Accept open-channel request.  Return a new Guile-SSH channel, or
@code{#f} on error.
@end deffn

@deffn {Scheme Procedure} message-get-type message
Get type of the @var{message} in the following format:

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

The procedure returns @code{#f} on error.

Example:

@lisp
(message-get-type msg)
@result{} '(request-auth auth-method-none)
@end lisp

Possible types:

@table @samp
@item request-auth
Subtypes:

@table @samp
@item auth-method-unknown
@item auth-method-none
@item auth-method-password
@item auth-method-publickey
@item auth-method-hostbased
@item auth-method-interactive
@end table

@item request-channel-open
Subtypes:

@table @samp
@item channel-unknown
@item channel-session
@item channel-direct-tcpip
@item channel-forwarded-tcpip
@item channel-x11
@end table

@item request-channel
Subtypes:

@table @samp
@item channel-request-unknown
@item channel-request-pty
@item channel-request-exec
@item channel-request-shell
@item channel-request-env
@item channel-request-subsystem
@item channel-request-window-change
@end table

@item request-service
@item request-global
Subtypes:

@table @samp
@item global-request-unknown
@item global-request-tcpip-forward
@item global-request-cancel-tcpip-forward
@end table

@end table
@end deffn

@deffn {Scheme Procedure} message-get-req message
Get a request object from the @var{message}.  Returns a new request
object (@pxref{Parsing of Requests}).  Throw @code{guile-ssh-error} on
error.
@end deffn

@deffn {Scheme Procedure} message-auth-set-methods! message methods-list
Set authentication methods to @var{methods-list}.  Possible methods
are: @code{password}, @code{public-key}, @code{interactive},
@code{host-based}.  Throw @code{guile-ssh-error} on error.  Return
value is undefined.
@end deffn

@deffn {Scheme Procedure} message-get-session message
Get the session from which the @var{message} was received.  Return the
session.
@end deffn

@node Parsing of Requests
@subsection Parsing of Requests

@cindex handling of requests
@tindex request

@deffn {Scheme Procedure} service-req:service request
Get service name from a service @var{request}.
@end deffn

@deffn {Scheme Procedure} channel-open-req:orig request
@deffnx {Scheme Procedure} channel-open-req:orig-port request
@deffnx {Scheme Procedure} channel-open-req:dest request
@deffnx {Scheme Procedure} channel-open-req:dest-port request
Get originator, originator-port, destination and destination-port from
the channel-open @var{request}.
@end deffn

@deffn {Scheme Procedure} auth-req:user request
@deffnx {Scheme Procedure} auth-req:password request
@deffnx {Scheme Procedure} auth-req:pubkey request
@deffnx {Scheme Procedure} auth-req:pubkey-state request
Get user, password, public key and public key state from the auth
@var{request}.
@end deffn

@deffn {Scheme Procedure} pty-req:term request
@deffnx {Scheme Procedure} pty-req:width request
@deffnx {Scheme Procedure} pty-req:height request
@deffnx {Scheme Procedure} pty-req:pxwidth request
@deffnx {Scheme Procedure} pty-req:pxheight request
Get terminal, terminal width, terminal height, terminal pxwidth and
terminal pxheight from the @acronym{PTY} @var{request}.
@end deffn

@deffn {Scheme Procedure} env-req:name request
@deffnx {Scheme Procedure} env-req:value request
Get environment variable name and its value from the environment
@var{request}.
@end deffn

@deffn {Scheme Procedure} exec-req:cmd request
Get a command from the exec @var{request}.
@end deffn

@deffn {Scheme Procedure} global-req:addr request
@deffnx {Scheme Procedure} global-req:port request
Get address and port from the global @var{request}.
@end deffn

@c Local Variables:
@c TeX-master: "guile-ssh.texi"
@c End: