1/*
2 * Copyright (c) 2009-2013 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
26Amanda::NDMP - communicate via NDMP
27
28=head1 SYNOPSIS
29
30  use Amanda::NDMP qw( :constants );
31
32  my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
33					       $password, $auth);
34  my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
35
36=head1 DESCRIPTION
37
38This package interfaces with the C class C<NDMPConnection> class declared in
39C<ndmp-src/ndmpconnobj.h>.  It is only available in builds that did not specify
40C<--without-ndmp>.  The C class, in turn, interfaces to the XDR code provided
41by NDMJOB, which sends and receives NDMP messages on a TCP socket.
42
43=head2 Constructor
44
45  my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
46					       $password, $auth);
47  if ($conn->err_code()) {
48    # handle error..
49  }
50
51This gets a new connection object.  This will always return an object, but the
52result should be checked for errors as described in the "Error Handling"
53section, below.
54
55The C<$host> and C<$port> give the NDMP server's host and port, respectively.
56The C<$auth> parameter defines the authentication mechanism to use: "md5" or
57"text"; "none" for no authentication; or "void" to not send any authentication
58packets at all.  For md5 or text modes, C<$username> and C<$password> specify
59the username and password for the NDMP server; these parameters must always be
60included, but can be blank for none or void.
61
62The C<$ident> parameter deserves some explanation.  NDMP scopes many
63server-side variables to the NDMP connection - for example, the "current" tape
64and taper state are associated with the NDMP connection.  To facilitate this,
65the constructor returns the I<same connection> for any constructor invocation
66with the same host, port, and identifier.  In cases where multiple connections
67are required (e.g., when two tapes are in use simultaneously), callers should
68provide different identifiers for each connection.
69
70=head2 Methods
71
72Note that not all NDMPConnection methods are available.  All of these methods
73block until the appropriate reply is received.  The underlying C class provides
74appropriate locking fundamentals to prevent corrupted on-the-wire messages.
75
76All methods return a boolean "ok" status, with false indicating an error.
77
78=head3 Error Handling
79
80  my $code = $conn->err_code();
81  my $msg = $conn->err_msg();
82
83Get the error code and message from the last method that returned false, or
84after the constructor is invoked.
85
86  $conn->set_verbose(1);
87
88This method will enable verbose logging of the NDMP transactions to the Amanda
89debug logs.
90
91=head3 SCSI Interface
92
93  my $ok = $conn->scsi_open($device);	    # NDMP_SCSI_OPEN
94  my $ok = $conn->scsi_close();		    # NDMP_SCSI_CLOSE
95  # NDMP_SCSI_EXECUTE_CDB
96  my $res = $conn->scsi_execute_cdb(
97    flags => $flags,
98    timeout => $timeout,
99    cdb => $cdb,
100    datain_len => $datain_len,	    # only if $flags == $NDMP9_SCSI_DATA_DIR_IN
101    dataout => $dataout 	    # only if $flags == $NDMP9_SCSI_DATA_DIR_OUT
102  )
103
104The first two methods are clear; the third uses keyword parameters to simplify
105a complex set of parameters.  The C<flags> argument can be
106C<$NDMP9_SCSI_DATA_DIR_IN>, to take data I<into> the server from the SCSI
107device, or C<$NDMP9_SCSI_DATA_DIR_OUT> to send data I<out> to the SCSI device.
108The C<timeout> is in milliseconds.  The C<cdb> should be a SCSI control block
109(the C<pack> function is useful here).  If the data direction is in, then
110C<datain_len> indicates the maximum amount of data to expect; otherwise,
111C<dataout> is the data to send to the device.
112
113The result is C<undef> for an error, or a hashref with the following keys:
114
115  status	    SCSI status byte
116  ext_sense	    SCSI extended sense data
117  datain	    data from the device
118  dataout_len	    number of bytes actually transmitted to the device
119
120=head3 Tape Interface
121
122  my $ok = $conn->tape_open($device, $mode);
123  my $ok = $conn->tape_close();
124
125The first method opens a tape device, using the give mode -
126C<$NDMP9_TAPE_READ_MODE> or C<$NDMP9_TAPE_RDRW_MODE>.  The second method closes
127the tape device associated with this connection.
128
129  my ($ok, $resid) = $conn->tape_mtio($op, $count);
130
131This method sends C<NDMP_TAPE_MTIO> with the given operation and count.
132Operations have the prefix C<$NDMP9_MTIO_>.  The number of incomplete
133operations is returned in C<$resid>.
134
135To read and write blocks, use these methods:
136
137  my ($ok, $actual) = $conn->tape_write($data);
138  my ($ok, $data) = $conn->tape_read($bufsize);
139
140where C<$actual> and C<$bufsize> are byte counts, and C<$data> is a string of
141data.  Finally, to get the state of the tape agent, use
142
143  my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
144
145=head2 Constants
146
147The constants required for the interface exposed here are included in this
148package.  They all begin with the prefix C<$NDMP9_>, which is an implementation
149detail of the NDMJOB library.  The constants are available from the export tag
150C<constants>:
151
152  use Amanda::NDMP qw( :constants );
153
154=cut
155
156
157%}
158