The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Crypt-License-2.04
River stage zero No dependents
1 ++
/ 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)