/ 
Device-ScanShare-1.014
River stage zero No dependents
/ Device::ScanShare

NAME

Device::ScanShare - manage USERDIRTS.TXT ecopy file to manage scanner device options

SYNOPSYS

	use Device::ScanShare;
   
	my $scanshare = new Device::ScanShare({
		userdirs_abs_path => '/var/www/Content/USERDIRS.TXT', 
			# therefore all paths saved are /var/www/Content/$PATH
		server => '192.168.0.150',	
		default_host => 'Dyer05',		
	});
   
	$scanshare->user_add({
		label=>'Martin', 
		path=>'/home/martin/incoming',
	});
   
	$scanshare->save;

DESCRIPTION

ScanShare is a oo module to work with the USERDIRS.TXT file used by ecopy for use with their ShareScan software. This enables you to control what the entries are via perl. You can add and remove entries to the file.

MOTIVATION

We use ecopy and sharescan software in the office. This is so someone can step up to the scanner and scan to a predetermined place. They have a little touchscreen.. you punch in where you want to send it to, the name of the file, and voila. What you can select from is controlled via a file called USERDIRS.TXT. In it are entries like ;

The Label=relative\dir\path,The Label,HostName,1,0

You can edit the damn thing in a text editor. If you have a jillion entries (like we have, upwards of 500), then you do not want to micro manage this by either using their crippled interface or via a text editor. Linux and perl to the rescue.

Included is also a utility called sharescan that will let you edit the file via the command line. It is called scanshare.

METHODS

new()

Argument is hash ref.

Arguments in hash ref are:

1. 'userdirs_abs_path': the path to the userdirs file 2. 'server': the server ip as per USERDIRS.TXT 3. 'default_host': the host for each line (Dyer05 in this example)

my $scanshare = new Device::ScanShare({
	userdirs_abs_path => '/var/www/Content/USERDIRS.TXT',
	server => '192.168.0.150',	
	default_host => 'Dyer05',
});

userdirs_abs_path()

Takes no argument, abs path to USERDIRS.TXT file. Must be provided via constructor.

abs_base()

Perl setget method, abs path to where USERDIRS.TXT resides, doesn't need to be provided. Entries start from here.

create()

Takes no argument. Called after adding users or to create blank file. Will warn and return false if already on disk.

Will create a new USERDIRS.TXT file in the argument provided to the constructor. That is, if you want to create a new file:

my $s = new Device::ScanShare({
	userdirs_abs_path => cwd().'/t/USERDIRS.TXT',
	server => '192.168.0.150',
	default_host => 'Dyer05',
});

$s->create;

create() will return true or false, will carp if file already exists or if create is not successful.

exists()

Takes no argument. Returns boolean.

Checks if userdirs file exists already or not.

exists_label()

Argument is label string. Checks if there is an entry with this label. Returns bool.

exists_path()

Argument is path. Checks if there is an entry with this path. Returns bool.

get_users()

Returns array ref with hashes of data for each userdirs entry- if you have made any additions or removals, this is reflected. Results are orderded by 'label'.

This method is also used internally to save.

my @all = $scanshare->get_users();

get_user()

get userdirs line entry data by path, returns hash

my $userx = $scanshare->get_user('/path/to/target_directory');
print $userx->{label} . ' is set up to scan to directory: '. $userx->{path};

save()

save changes to userdirs file

$scanshare->save();

count()

Returns how many userdirs there are

my $count = $scanshare->count();

METHODS FOR ADDING AND REMOVING ENTRIES

Please note user_add() and user_delete() will save changes to the file.

user_add()

insert new userdir into records, takes arguments label, and absolute path. returns 0 if it already exists (by path), returns 1 on success.

my $path = '/path/to/dirx';
my $label = 'a new scan destination';

$scanshare->user_add({ label=>$label, path=>$path }) 
	or die("entry already existed for the destination $path");

user_delete()

delete user record, takes absolute path to directory that it saves to as argument

$scanshare->user_delete('/path/to/target_directory');
$scanshare->save(); # optionally save it to commit changes.

returns 1 on success returns nothing if entry did not exist

BUGS

Please contact the AUTHOR with any problems, feature requests, or bugs. You can also file in http://rt.cpan.org

NOTES

Example of a valid USERDIRS.TXT file:

[PreferredServer]
Server=192.168.0.130
[RoutingID]
NextID=4
[Users]
Great Place=relative\to\userdirs\location,Great Place,Host04,1,0
Also a Great Place=relative\also,Also a Great Place,Host04,2,0
Documents=misc\documents,Documents,Host04,3,0

Note the increment 1, 2, 3.. This is taken care of this module.

AUTHOR

Leo Charre leocharre at cpan dot org

COPYRIGHT

Copyright (c) 2009 Leo Charre. All rights reserved.

LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".

DISCLAIMER

This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.