SharePoint::SOAPHandler(3pm)

NAME
SharePoint::SOAPHandler - Perl extension for providing a Sharepoint connecter instance for CopyTree::VendorProof.

This module provides CopyTree::VendorProof a connector instance with methods to deal with remote Sharepoint file operations.

IMPORTANT NOTICE: Your Implementation might not work unless you read this!
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);

For those of you with earlier versions of Authen::NTLM, see the historic segment below.

Also, if your Sharepoint connects through https, but does not go through a proxy server, even though all your OTHER http/ https traffic does, you must:

delete $ENV{'https_proxy'}

This is because when SOAP::Lite -> proxy calls SOAP::Transport, your %ENV is inspected for proxy settings. Specifying the https sharepoint domain on the no_proxy list will not mask https_proxy, because oddly, no_proxy only works for 'no http' and not 'no https'. These are just some annoying things I discovered. Your milage may vary.

----historic----

Please note that as of this writing in July 2011, there is an NTLM bug that needs to be hacked for the sharepoint connector SharePoint::SPCOPY to work. Basically, LWP normally automatically negotiates NTLM protocols, and calls its LWP::Authen::Ntlm to in turn call Authen::NTLM to authenticate against windows domains. The problem is, sharepoint prefers an authentication between ntlmv2 and ntlmv1 that's offered by the Authen::NTLM package. LWP::Authen::Ntlm does not specify any version. This causes authentication to fail on sharepoint. The web community offers a quick fix to 'patch' Authen::NTLM, which involves finding the Authen::NTLM module (perhaps in /usr/local/share/perl/5.10.1/Authen/NTLM.pm) and changing around line 289, where $domain =substr($challenge, $c_info->{domain}{offset}, $c_info->{domain}{len}); is to be changed to $domain = &unicode("domain"); This is CRITICALLY IMPORTANT if you want SharePoint::SOAPHandler to work. I have created a patch that is a varient of this solution, but does not break backwards compatibility. You can find this patch at

https://rt.cpan.org/Ticket/Display.html?id=70703

Remember, either of these fixes must be applied for this module to work. If the above instructions are unclear, please google http://shareperl.blogspot.com/2010/01/sharepoint-perl-connection.html.

----end historic----

SYNOPSIS
  use SharePoint::SOAPHandler;

To create a soaphandler connector instance:

        my $soaphandler_inst = SharePoint::SOAPHandler ->new;
        #set up connection parameters

        #IMPORTANT sp_creds_domain should not have the protocol (http or https://)
        $soaphandler_inst ->sp_creds_domain('www.sharepointsite.org:443');
        $soaphandler_inst ->sp_creds_user('DOMAIN_in_CAPs\username');
        $soaphandler_inst ->sp_creds_password('domain_password');
        $soaphandler_inst ->sp_authorizedroot('https://www.sharepointsite.org:443/some_dirs/the_dir_just_above_the_Shared_Documents_dir_that_you_are_allowed_to_edit');

To add a source or destination item to a CopyTree::VendorProof instance:

        my $ctvp_inst = CopyTree::VendorProof ->new;
        #All Sharepoint file operations defined in this module uses 'Shared Documents' as a starting root path.  To define
        #any file, you need not (and may not) provide the full uri.  Since Microsoft sometimes requests partial url and sometimes requests full
        #urls, I prefer to append information rather than match and remove information from a url string.  What?  I didn't see you writing a module
        #for sharepoint.
        $ctvp_inst ->src ('Shared Documents/path to your source', $soaphandler_inst);#all soaphandler paths starts with Shared Documents/
        $ctvp_inst ->dst ('Shared Documents/path to your destination', $soaphandler_inst);#all soaphandler paths starts with Shared Documents/

        $ctvp_inst ->cp;

        #this in effect creates

        'Shared Documents/path to your destination/source dir name'

        #if your source is a dir, or if your sources are a mixture of dirs and /or files.

        #If you're doing single file to single file copy, you would have

        'Shared Documents/path to your destination'

        #holding the content of your source file.

DESCRIPTION
SharePoint::SOAPHandler, in addition to providing an instance and methods for its parent class (CopyTree::VendorProof), also provides methods for interacting with sharepoint's getlistcollection items. These methods are not extensively tested and not supported. Not that any other methods are, but with these you are especially on your own.

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

The functionality of these methods are described in perldoc CopyTree::VendorProof and perldoc SharePoint::SOAPHandler

Instance Methods
Since these are class methods, the first item from @_ is the instance itself, and should be stored in $inst, or whatever you'd like to call it.

  0. new
        which takes no arguments, but blesses an anonymous hash into the data connection object and returns it

  1. fdls
        which takes two arguments:
                an option ($lsoption) that's one of 'f', 'd', 'fdarrayrefs', or ''
                and a directory path $startpath.
                The lsoption is passed to the SUPER class fdls_ret, and is not handled at this level.
        This method will generate @files and @dirs, which are lists of files and directories that start with $startpath,
        And return $self -> SUPER::fdls_ret ($lsoption, \@files, \@dirs),
        which is ultimately a listing of the directory content, being one of
                @files, @dirs, (\@files, \@dirs), or  @files_and_dirs) depending on the options being 'f', 'd', 'fdarrayrefs' or ''

  2. is_fd
        which takes a single argument of a file or dir $path,
        and returns 'd' for directory,
                'f' for file,
                'pd' for non-existing, but has a valid parent dir,
                '0' for non of the above.

  3. read_into_memory
        which takes the $sourcepath of a file,
        and reads (slurps) it into a scalar $binfile #preferably in binmode,
        and returns it as \$binfile

  4. write_from_memory
        which takes the reference to a scalar $binfile (\$binfile)  PLUS
        a destination path, and writes the scalar to the destination.
        no return is necessary

  5. copy_local_files
        which takes the $source and $destination files on the same file system,
        and copies from $source to $destination.  No return is necessary.  This
        method is included such that entirely remote operations may transfer faster,
        without an intermediate 'download to local machine' step.

  6. cust_mkdir
        which takes a $dirpath and creates the dir.  If the parent of $dirpah
        does not exist, give a warning and do not do anything

  7. cust_rmdir
        which takes a $dirpath and removes the entire dir tree from $dirpath
        croaks / dies if $dirpath is not a dir. No return is necessary.
        To make things easier, when writing this method, use

        my ($filesref, $dirsref) = $inst -> ls_tree_fdret( $dirpath, $inst -> ls_tree($dirpath);

        to get array references of @files and @dirs under $dirpath
        Note: ls_tree and ls_tree_fdret uses fdls, and are parent classes in CopyTree::VendorProof

  8. cust_rmfile
        which takes a $filepath and removes it.
        croaks / dies if $file is not a file.

SEE ALSO
CopyTree::VendorProof CopyTree::VendorProof::LocalFileOp

AUTHOR
dbmolester, dbmolester de gmail.com

COPYRIGHT AND LICENSE
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.