NAME

Filesys::SmbClientParser - Perl client to reach Samba ressources with smbclient

SYNOPSIS

  use Filesys::SmbClientParser;
  my $smb = new Filesys::SmbClientParser
  (undef,
   (
    user     => 'Administrateur',
    password => 'password'
   ));
  # Or like -A parameters:
  $smb->Auth("/home/alian/.smbpasswd");
  
  # Set host
  $smb->Host('jupiter');
  
  # List host available on this network machine
  my @l = $smb->GetHosts;
  foreach (@l) {print $_->{name},"\t",$_->{comment},"\n";}
  
  # List share disk available
  my @l = $smb->GetShr;
  foreach (@l) {print $_->{name},"\n";}
  
  # Choose a shared disk
  $smb->Share('games2');
  
  # List content
  my @l = $smb->dir;
  foreach (@l) {print $_->{name},"\n";}
  
  # Send a Winpopup message
  $smb->sendWinpopupMessage('jupiter',"Hello world !");
  
  # File manipulation
  $smb->cd('jdk1.1.8');
  $smb->get("COPYRIGHT");
  $smb->mkdir('tata');
  $smb->cd('tata');
  $smb->put("COPYRIGHT");
  $smb->del("COPYRIGHT");
  $smb->cd('..');
  $smb->rmdir('tata');
  
  # Archive method
  $smb->tar('c','/tmp/jdk.tar');
  $smb->cd('..');
  $smb->mkdir('tatz');
  $smb->cd('tatz');
  $smb->tar('x','/tmp/jdk.tar');

See test.pl file for others examples.

DESCRIPTION

SmbClientParser work with output of bin smbclient, so it doesn't work on win platform. (but query of win platform work of course)

A best method is work with a samba shared librarie and xs language, but on Nov.2000 (Samba version prior to 2.0.8) there is no public interface and shared library defined in Samba projet.

Request has been submit and accepted on Samba-technical mailing list, so I've build another module called Filesys-SmbClient that use features of this library. (libsmbclient.so)

For Samba client prior to 2.0.8, use this module !

SmbClientParser is adapted from SMB.pm make by Remco van Mook mook@cs.utwente.nl on smb2www project.

INTERFACE

Objects methods

new [PATH_OF_SMBCLIENT], [HASH_OF_PARAM]

Create a new FileSys::SmbClientParser instance. Search bin smbclient, and fail if it can't find it in standard location. (ENV{PATH}, /usr/bin, /usr/local/bin, /opt/bin or /usr/local/samba/bin/). If it's on another directory, use parameter PATH_OF_SMBCLIENT.

HASH_OF_PARAM is a hash with key user,host,password,workgroup,ipadress,share

Host [HOSTNAME]

Get or set the remote host to be used to HOSTNAME.

User [USERNAME]

Get or set the username to be used to USERNAME.

Share [SHARENAME]

Get or set the share to be used on the remote host to SHARENAME.

Password [PASSWORD]

Get or set the password to be used to PASSWORD.

Workgroup [WORKGROUP]

Get or set the workgroup to be used to WORKGROUP. See -W switch in smbclient man page.

IpAdress [IP]

Set or get the IP adress of the server to contact to IP See -I switch in smbclient man page.

Debug [LEVEL]

Set or get the debug verbosity

    0 = no output
    1+ = more output

Auth AUTH_FILE

Use the file AUTH_FILE for username and password. This uses User and Password instead of -A to be backwards compatible.

Network methods

GetGroups [HOSTNAME, USER, PASSWORD, WORKGROUP, IP]

If no parameters is given, field will be used.

Return an array with sorted workgroup listing that contains hashes; keys: name, master

GetShr [HOSTNAME, USER, PASSWORD, WORKGROUP, IP]

If no parameters is given, field will be used.

Return an array with sorted share listing, that contains hashes; keys: name, type, comment

GetHosts [HOSTNAME, USER, PASSWORD, WORKGROUP, IP]

Return an array with sorted host listing, that contains hashes; keys: name, comment

sendWinpopupMessage DEST, TEXT

This method allows you to send messages, using the "WinPopup" protocol, to another computer. If the receiving computer is running WinPopup the user will receive the message and probably a beep. If they are not running WinPopup the message will be lost, and no error message will occur.

The message is also automatically truncated if the message is over 1600 bytes, as this is the limit of the protocol.

Parameters :

DEST: name of host or user to send message TEXT: text to send

Operations

cd [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

If DIR is specified, the current working directory on the server will be changed to the directory specified. This operation will fail if for any reason the specified directory is inaccessible. Return list.

If no directory name is specified, the current working directory on the server will be reported.

dir [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

Return an array with sorted dir and filelisting that contains hashes; keys: name, attr, size, date

mkdir NAME, [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

Create a new directory on the server with the specified name NAME

rmdir NAME, [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

Remove the specified directory NAME from the server. NAME can be a pattern.

get FILE, [TARGET, DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

Gets the file FILE, using USER and PASSWORD, to TARGET on current SMB server and return the error code.

If TARGET is unspecified, current directory will be used For use STDOUT, set target to '-'.

del FILE, [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

The client will request that the server attempt to delete all files matching FILE from the current working directory on the server

rename SOURCE, TARGET, [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

The file matched by mask SOURCE will be moved to TARGET. These names can be in different directories. It returns a return value.

pwd

Returns the present working directory on the remote system. If there is an error it returns undef. If you are on smb://jupiter/doc/mysql/, pwd return \doc\mysql\.

du [DIR, UNIT]

If no path is given current directory is used.

UNIT can be in [kbsmg].

b: Posix blocks
k: 1Kbyte blocks
s: Samba blocks
m: 1Mbyte blocks
g: 1Gbyte blocks

If no unit given, k is used (1kb bloc)

In scalar context, return the total size in units for files in current directory.

In array context, return a list with total size in units for files in directory, size left in partition of share, block size used in bytes, total size of partition of share.

mget FILE, [RECURSE]

Gets file(s) FILE on current SMB server,directory and return the error code. If multiple file, push an array ref as first parameter or pattern * or file separated by space

Syntax:

  $smb->mget ('file'); #or
  $smb->mget (join(' ',@file); #or
  $smb->mget (\@file); #or
  $smb->mget ("*",1);

put ORIG,[FILE, DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP]

Puts the file $orig to $file, using USER and PASSWORD on courant SMB server and return the error code. If no $file specified, use same name on local filesystem. If $orig is unspecified, STDIN is used (-).

mput FILE, [RECURSE]

Puts file(s) $file on current SMB server,directory and return the error code. If multiple file, push an array ref as first parameter or pattern * or file separated by space

Syntax:

  $smb->mput ('file'); #or
  $smb->mput (join(' ',@file); #or
  $smb->mput (\@file); #or
  $smb->mput ("*",1);

Archives methods

tar($command, $target, [DIR, HOSTNAME ,USER, PASSWORD, WORKGROUP, IP])

Execute TAR commande on //HOSTNAME/$share/DIR, using USER and PASSWORD and return the error code. $target is name of tar file that will be used

Syntax: $smb->tar ($command,'/tmp/myar.tar') where command is in ('x','c',...). See smbclient man page for more details.

Error methods

All methods return undef on error and set err in $smb->err.

err: Return last text error that smbclient found
LastResponse: Return last buffer return by smbclient

Private methods

byname: sort an array of hashes by $_->{name} (for GetSMBDir et al)
operation(...)
command($args,$command)

VERSION

$Revision: 2.5 $

TODO

Write a wrapper for ActiveState release on win32

Correct this documentation with a good english ...

AUTHOR

Alain BARBET alian@alianwebserver.com