git.gag.com Git - debian/amanda/blob - perl/Amanda/IPC/Binary.pod

   1 /*
   2  * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 %perlcode %{
  23
  24 =head1 NAME
  25
  26 Amanda::IPC::Binary - binary-framed message-based communication
  27
  28 =head1 SYNOPSIS
  29
  30 See below.
  31
  32 =head1 DESCRIPTION
  33
  34 This package is an interface to the C-level protocol library declared in
  35 C<common-src/ipc-binary.h>.  It enables two-way message-based communication,
  36 using a binary framing that permits direct inclusion of non-string data.
  37
  38 Unlike the line protocol (see L<Amanda::IPC::LineProtocol>), this package does
  39 not yet support asynchronous operation.
  40
  41 =head2 DEFINING A PROTOCOL
  42
  43 There are two parts to any use of this package.  First, define the protocol by
  44 creating a subclass and populating it.  This subclass represents the protocol,
  45 composed of a set of commands or messages and arguments that are attached to
  46 those commands.
  47
  48 Begin with the subclass:
  49
  50     package TestProtocol;
  51     use base "Amanda::IPC::Binary";
  52     use Amanda::IPC::Binary;
  53
  54 Then define the constants for each command.  Note that the C<constant> pragma did
  55 not support the hash syntax in Perl-5.6, so this must be written as individual
  56 invocations of the constant:
  57
  58     use constant CMD1 => 1;
  59     use constant CMD2 => 2;
  60
  61 Then the constants for each argument:
  62
  63     use constant USERNAME => 1;
  64     use constant PASSWORD => 2;
  65     use constant RESOURCE => 3;
  66     use constant USE_OVERDRIVE => 4;
  67
  68 Next, give the magic value for the protocol:
  69
  70     magic(0x9812);
  71
  72 Then begin defining each command, along with its arguments:
  73
  74     command(CMD1,
  75         RESOURCE, 0,
  76         USERNAME, $IPC_BINARY_STRING,
  77         PASSWORD, $IPC_BINARY_STRING|$IPC_BINARY_OPTIONAL);
  78
  79 The first argument to C<command> specifies the command ID.  The remaining
  80 arguments are taken in pairs, and specify the argument and a bitfield of
  81 flags.  The available flags are:
  82
  83     $IPC_BINARY_STRING      argument is a printable string
  84     $IPC_BINARY_OPTIONAL    argument is not required
  85
  86 If $IPC_BINARY_STRING is not specified, the argument can contain any sequence of
  87 bytes (including nuls). In either case, a perl string is used to represent it.
  88
  89 =head2 USING A PROTOCOL
  90
  91 Once a protocol is defined, it forms a class which can be used to run the
  92 protocol.  Multiple instances of this class can be created to handle
  93 simultaneous uses of the protocol over different channels.
  94
  95 The constructor takes no parameters, but establishs a new channel, complete with
  96 buffers for partially-read commands:
  97
  98     my $chan = TestProtocol->new();
  99
 100 To write a message, call the C<write_message> method, passing a filehandle, a
 101 command id, and argument/value pairs:
 102
 103     if (!$chan->write_message($fh, TestProtocol::CMD1,
 104             TestProtocol::RESOURCE => $res,
 105             TestProtocol::USERNAME => "dustin")) {
 106         # ...
 107     }
 108
 109 It is not valid to omit an argument value, and all values must be perl strings
 110 -- C<undef> is not alloewd, even for optional arguments.  If C<write_message>
 111 fails, it returns false and C<$!> is set appropriately.  The function does not
 112 return until the message has been written to the file.
 113
 114 To read a message, call C<read_message>, again passing a filehandle:
 115
 116     my $msg = $chan->read_message($fh);
 117
 118 Note that this will block until a full message has been read.  The resulting
 119 message object has a C<cmd_id> key that identifies the command and an C<args>
 120 key that references a list of argument values, keyed by their argument ID:
 121
 122     if ($msg->{'cmd_id'} == TestProtocol::CMD2) { ... }
 123     print $msg->{'args'}[TestProtocol::USERNAME], "\n";
 124
 125 The C<close> method will flush any open buffers and close a channel.  In the
 126 synchronous case, this is essentially a no-op since all output buffers are
 127 flushed at each call to C<write_message>.
 128
 129 =cut
 130
 131 %}