/ 
Crypt-License-2.04
River stage zero No dependents
/ Crypt::License::Util

NAME

Crypt::License::Util - Perl extension to examine a license file.

USEAGE

use Crypt::License::Util

SYNOPSIS

use Crypt::License::Util

$file_path = license4server;
$file_path = path2License([optional lic file name]);
deprecated $callr_pkg = chain2next($ptr2_License_hash);
$prev_module = chain2prevLicense;
$rv=exportNext2(Package::Name,[next::name],[...]);
$rv=requireLicense4(Package::Name,[next::name],[...]);
$rv=modules4privateList(Package::Name,[next::name],[...]);
$rv=requirePrivateLicense4(Package::Name,[next::name],[...]);

DESCRIPTION

$file_path = license4server;
Creates $ptr2_License in calling module if necessary.

Sets:	'path' => '/web/server/license/path/README.LICENSE'

ONLY for the root user. Dies otherwise.
$file_path = path2License([optional lic file]);
  Creates $ptr2_License in calling module if necessary.

  Sets the following:
  $ptr2_License = {
	'path' => '/user/home/README.LICENSE'
	}; 
	as the default or to 
	'path' => '/user/home/some/path/optional.name'
	if a relative file path/name is supplied

  In both cases the absolute /file/path is returned.
$callr_pkg = chain2next($ptr2_License_hash);

DEPRECATED

  Sets the following in the calling (current) package:
  $ptr2_License = {'next' => 'previous caller package name';
	and returns this value. This is a convenience and is
	not currently use for anything. IT MAY CHANGE!
$prev_module = chain2prevLicense;
  Creates $ptr2_License in calling module if necessary.

  Sets the following:
	$ptr2_License = {
	'next' => 'previous module name'
	};
$rv=exportNext2(Package::Name,[next::name],[...]);
Sets the following in the target Package::Name:
$ptr2_License = {'next' => 'this (current) package name'};
if $ptr2_License does not exist in the target package;

returns # of exports to modules with no $ptr2_License.
returns 0 if no exports were needed
$rv=requireLicense4(Package::Name,[next::name],[...]);
  The same as:
	require Package::Name;
	$rv += exportNext2(Package::Name);
	repeated for list.....

To achive the equivalent of something like:

use Package::Name

you can try:

require Package::Name;
import Package::Name  qw(list of args);
exportNext2(Package::Name);

however, this construct does not work for some packages, notably the ones using the Class::Struct module. A better approach for modules that are not encrypted but that need a $ptr2_License is to simple 'use' them in the normal fashion and call the exportNext2 method later.

$rv=modules4privateList(Package::Name,[next::name],[...]);

Creates the entry:

$ptr2_License = {
 'private' => 'Package::Name,[next::name],[...]'
};

..in the calling module. Returns the hash value string.

$rv=requirePrivateLicense4(Package::Name,[next::name],[...]);
  The same as:
	require Package::Name;
	exportNext2(Package::Name);
	repeated for list....
  followed by:
	$rv=modules4privateList(Package::Name,[next::name],[...])

By default the LICENSE file must be located in the users home directory and the calling file uid must belong to that user. If this is not the case, create $ptr2_License manually rather than using the module call.

HOWTO

Every module that imports a licensed module must contain a HASH pointer for the License object. The pointer and object may be created manually or using the Crypt::License::Util tool set. The License object may contain one or more of the following entries:

use vars qw( $ptr2_License );
$ptr2_License = {
     'private'   => 'name1, name2,...',  # use private key 
                                         # module name
     'path'      => 'path to License file',
     'next'      => 'caller module name',
     'expires    => 'seconds until expiration',
     'warn'      => 'warning messages',  # not implemented
 };

In addition there are other keys that are used by the Crypt::License::Notice module including but not limited to:

'ACTION'    => 'mailer action',
'TMPDIR'    => 'path to writable tmp dir',
'INTERVALS' => 'reporting intervals',
'TO'        => 'notice delivery email target',

A module which will call a Licensed module must provide a HASH pointer and key/value pairs for a either next or path (and private if required) in order to successfuly import the module. The HASH pointer must be instantiated from within the module, not assumed from a prior export from a parent module. The following Crypt::License::Util routines instantiate the HASH pointer '$ptr2_License':

license4server	 {path} => useable only by root
path2License		 {path} => /user/home/README.LICENSE
chain2next		DEPRECATED
chain2prevLicense	 {next} => caller module name

Exports of the HASH pointer are useful for Licensed modules which provide subprocesses to non-Licensed modules such as the handlers for Apache-AuthCookie. The following Crypt::License::Util routines export the HASH pointer '$ptr2_License' automatically:

exportNext2		 {next} => caller module name
requireLicense4	 {next} => caller module name
requirePrivateLicense4 {next} => caller module name

For Licensed module calls of usr Private modules, the private key must be set with the module names. The following Crypt::License::Util routines will automatically instantiate the private key:

modules4private	 {private} => module,name,scalar
requirePrivateLicense4 {private} => module,name,scalar

EXAMPLES: example 1: Parent module XYZ package XYZ; use Crypt::License::Util; path2License; requireLicense4('Module::A','Module::B'); requirePrivateLicense4('User::X','User::Y');

  This is the same as:
	package XYZ;
	use vars qw($ptr2_License);
	$ptr2_License = {
		'path' => '/usr/homedir/README.LICENSE'};
	require Module::A;
	require Module::B;
	$Module::A::ptr2_License = 
		\%Module::A::{'next' => 'XYZ'};
	$Module::B::ptr2_License = 
		\%Module::B::{'next' => 'XYZ'};
	$ptr_License->{private} = 'User::X,User::Y';
	require User::X;
	require User::Y;
	$User::X::ptr2_License = 
		\%User::X::{'next' => 'XYZ'};
	$User::Y::ptr2_License = 
		\%User::Y::{'next' => 'XYZ'};

  example 2:
	package Module::A;
	use Time::Local;
	use Crypt::License::Util;
	exportNext2('Time::Local');
	chain2prevLicense;
	requireLicense4('Delta::Module');

  This is the same as:
	package Module::A;
	use Time::Local
	use vars qw($ptr2_License);
	$Time::Local::ptr2_License = 
		\%Time::Local::{'next' => 'Module::A'};
	$ptr2_License = {'next' => 'XYZ'};
	require Delta::Module;
	$Delta::Module::ptr2_License =
		\%Delta::Module::{'next' => 'Module::A'};

  To notify YOU of License expiration, add the 
  following to module XYZ:
	....
	use Crypt::License::Notice;
	if ( exists $ptr2_License->{expires} ) {
		require Crypt::License::Notice;
		Crypt::License::Notice->check($ptr2_License);
	}

		
  example 3: This is for an apache web server.

  In B<startup.pl>
	....
	use lib qw(/usr/local/apache/libhandlers);
	$main::ptr2_License = {
		'path' => '/usr/local/apache/README.LICENSE'
	};
	
  In handlers called from PerlRequire or PerlHandler
	package Lmnop;
	....
	Apache::AuthCookie;
	use Crypt::License::Util;
	license4server;
	requireLicense4('WhatEver::Module');
	exportNext2('Apache::AuthCookie');

  This is the same as:
	package Lmnop;
	....
	use Apache::AuthCookie;
	use vars qw($ptr2_License);
	$ptr2_License = {
		'/usr/local/apache/README.LICENSE'
	};
	require WhatEver::Module;
	$WhatEver::Module::ptr2_License =
		\%WhatEver::Module::{'next' = 'Lmnop'};
	$Apache::AuthCookie::ptr2_License =
		\%Apache::AuthCookie::{'next' = 'Lmnop'};

  ... continuing calling Lmnop from user space...
	package User::Space;
	use Crypt::License::Util;
	path2License;
	..... 
	# Lmnop loaded by mod_perl handler
	# sees User::Space as it's caller
	&Lmnop->function1(args);

  This is the same as:
	package User::Space;
	use vars qw($ptr2_License);
	$ptr2_License = {
		'path' => '/user/home/README.LICENSE');
	
	&Lmnop->function1(args);

EXPORTS

license4server
path2License 
chain2next 
chain2prevLicense
exportNext2
requireLicense4
modules4private
requirePrivateLicense4

AUTHOR

Michael Robinton, michael@bizsystems.com

COPYRIGHT

Copyright 2001 Michael Robinton, BizSystems. All rights reserved.

SEE ALSO

perl(1), Crypt::License(3)