NAME

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

USEAGE

SYNOPSIS

$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:

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;
exportNext2('Time::Local');
chain2prevLicense;
requireLicense4('Delta::Module');
This is the same as:
package Module::A;
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:
....
if ( exists $ptr2_License->{expires} ) {
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;
license4server;
requireLicense4('WhatEver::Module');
exportNext2('Apache::AuthCookie');
This is the same as:
package Lmnop;
....
use vars qw($ptr2_License);
$ptr2_License = {
'/usr/local/apache/README.LICENSE'
};
$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;
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)