CopyTree-VendorProof version 0.0011
==============================================

This module provides a generic interface to inplement a copy method between [a local computer and a remote file system] or [a remote file system and itself] or [local computer to local computer]. 

The supported (very basic) copy funtionalities mimics the unix cp -rf command - copies SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

This module is written for file copies to and from a remote file system that cannot be mounted; for example, the Microsoft Sharepoint web service (as of 2011).  To use the methods in this module, you must provide objects that act as connectors to the remote file system and / or the local file system (More details about the methods required in these connector modules below).  For example, if you want to copy locally a file to a dir (I don't know why you would want to use this module for that, unless you're on a very silly OS that doesn't handle copy well), you must provide an extra object that provides basic methods for local file copying.  I have written one for local, named CopyTree::VendorProof::LocalFileOp.  

If you would like to copy between local to remote, you must also provide the connector object for the remote.  I have written one for sharepoint, called SharePoint::SOAPHandler.  

If you would like to copy to and from a variety of remote and local file systems, you must include connecter objects for these systems, and all of which will use this module as a base class.  In other words, this module is quite useless by itself, yet other modules like SharePoint::SOAPHandler and CopyTree::VendorProof::LocalFileOp depends on it.  In all likeliness, you have to use these 3 modules in your script to complete a copy operation - the two connectors to provide basic copy / ls methods, and this module to provide the cp -rf functionality.

The primary use of this module is on a linux / unix system that needs to interact with a remote system.  This module is not tested on Macs.

Currenly, you need to install Authen::NTLM version 1.09 or greater for this module to work.  With my v1.09 tweak to Authen::NTLM on CPAN, this module should just work.  If you actually use Authen::NTLM directly for some reason, remember to set

ntlmv2('sp');

prior to using SharePoint::SOAPHandler.  You did remember to export ntlmv2, no?

use Authen::NTLM qw(ntlmv2);

The methods provided in this module (base class) include:
	new
	reset
	src
	dst
	cp
	copy_meth_deci
	ls_tree
	ls_tree_fdret
	path
	fdls_ret
	
	Of the aformentioned methods, new, path, and reset are the only methods that do not require additional connector objects to function, although path has the sole function of providing a base class to connector objects.

The methods required in the connector objects include:
	new
	fdls				
	is_fd
	read_info_memory
	write_from_memory
	copy_local_files
	cust_mkdir
	cust_rmdir
	cust_rmfile

How to write connector methods ($_[0] holds the class / instance itself, arguments mentioned below are in $_[1] and onwards):

	new:	Takes no arguments, but blesses an anonymous hash into the data connection object and returns it

	fdls:  Pass in $lsoption, $path	
		Where $lsoption is 'd', 'f', 'fdarrayrefs', or '', 
		and $path is the path of the directory to be listed.	
		The lsoption is passed to the SUPER class fdls_ret, and is not handled at this level.
		Required action:
		You must put all the files found in $path in @files, and all the dirs in @dirs, then
		return $self->SUPER::fdls_ret ($lsoption, \@files, \@dirs).

	is_fd: Pass in $query
		Where $query is the file or dir in question to do a file test.
		Required action:
		For the specific $query, the return must be 'f' for file, 'd' for directory, 'pd' for
		a non existing file / dir that has a valid parent, and 0 for everything else.

	read_into_memory: Pass in $sourcepath
		Where $sourcepath is the file to read.
		Required action:
		The return must be a reference to a scalar, which holds the contents of the file
		in bin mode.
	
	write_from_memory: Pass in $bincontentref, $dest
		Where $bincontentref is a reference to a scalar, which holds the content of a file 
		in bin mode, and $dest is the file name to write the content to.
		Required action: 
		The method will write the content of the file onto the file system, using the $dest
		specified.
		No return is necessary.

	copy_local_files: Pass in $source, $dest
		Where $source is the $source path of a file, and $dest is a destination path on 
		the same file system.  
		Required Action:
		This method is written such that purely remote operations
		do not require an intermediate step of holding each file in memory. 
		The $source file is copied and saved to the file name specified by 
		$dest.
		No return is necessary.
	
	cust_mkdir: Pass in $path
		Where $path is the dir name to be created.
		Required action:
		Create the dir as specified by $path.
		No return is necessary.

	cust_rmdir: Pass in $path
		Where $path is the dir name to be removed.	
		Required action:
   	Removes the dir as specified by $path.  If items / files / other dirs exists under $path,
		recursively remove them.  
		No return is necessary.

	cust_rmfile: Pass in $filepath
		Where $filepath is the path of the file
		Required action
		removes the file as specified by path.  dies/ croaks if $filepath is not a file
		No return is necessary.



INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

Carp
Data::Dumper

COPYRIGHT AND LICENCE


Copyright (C) 2011 by dbmolester

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.


