1 # Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 # All rights reserved.

     3 # This component and the accompanying materials are made available

     4 # under the terms of the License "Eclipse Public License v1.0"

     5 # which accompanies this distribution, and is available

     6 # at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 # 

     8 # Initial Contributors:

     9 # Nokia Corporation - initial contribution.

    10 # 

    11 # Contributors:

    12 # 

    13 # Description:

    14 # 

    15 #

    16 # Description:

    17 # Symbian::IPR

    18 #

    19 

    20 package Symbian::IPR;

    21 

    22 use strict;

    23 use Carp;

    24 use Symbian::CBR::IPR::MRP;

    25 use Symbian::DistributionPolicy::Reader;

    26 

    27 use base qw(Class::Singleton);

    28 

    29 

    30 sub _new_instance {

    31     my $pkg = shift;

    32     my $useDistPolFirst = shift;

    33     my $disallowUnclassifiedSource = shift;

    34     my $typeOfMrp = shift;

    35     my $verbose = shift;

    36     my $captureDistributionPolicyOutput = shift;

    37     

    38     if (!$typeOfMrp || shift) {

    39         # caller(0))[3] gives the package and the method called, e.g. Symbian::IPR::_new_instance

    40         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";

    41     }

    42 

    43     my $self = {

    44             'useDistPolFirst' => $useDistPolFirst,

    45             'disallowUnclassifiedSource' => $disallowUnclassifiedSource,

    46             'verbose' => $verbose,

    47             'typeOfMrp' => $typeOfMrp,

    48             'captureDistributionPolicyOutput' => $captureDistributionPolicyOutput};

    49 

    50     bless $self, $pkg;

    51 

    52     if (!$useDistPolFirst) {

    53         # If we are not using distribution policy files as default then create a Symbian::CBR::IPR::MRP object... 

    54         $self->CreateMrpObject();

    55     }

    56     

    57     return $self;

    58 }

    59 

    60 sub CreateMrpObject {

    61     my $self = shift;

    62     

    63     if (!exists $self->{'mrpObject'}) {

    64         $self->{'mrpObject'} = Symbian::CBR::IPR::MRP->instance($self->{typeOfMrp}, $self->{verbose});

    65     }

    66     

    67     # We may have cached calls to PrepareInformationForComponent...

    68     if (defined $self->{prepareInformationForComponentCache}) {

    69         foreach my $component (@{$self->{prepareInformationForComponentCache}}) {

    70             $self->PrepareInformationForComponent($component);

    71         }

    72         delete $self->{prepareInformationForComponentCache};

    73     }

    74     

    75     # and also to PrepareInformationForMrpFile...

    76     if (defined $self->{prepareInformationForMrpFileCache}) {

    77         $self->PrepareInformationForMrpFile->(@{$self->{prepareInformationForMrpFileCache}});

    78         delete $self->{prepareInformationForMrpFileCache};

    79     }

    80 }

    81 

    82 sub PrepareInformationForComponent {

    83     my $self = shift;

    84     my $component = shift;

    85     

    86     # An MRP object may not have been created, for example if using distribution policy files first.

    87     # In that case we cache the calls to PrepareInformationForComponent, and will pass them onto the

    88     # MRP object if it is ever created.

    89     if (defined $self->{'mrpObject'}) {

    90         $self->{'mrpObject'}->PrepareInformationForComponent($component);

    91     }

    92     else {

    93         push @{$self->{prepareInformationForComponentCache}}, $component;

    94     }

    95 }

    96 

    97 sub PrepareInformationForMrpFile {

    98     my $self = shift;

    99     my @mrps = shift;   

   100 

   101     # An MRP object may not have been created, for example if using distribution policy files first.

   102     # In that case we cache the calls to PrepareInformationForMrpFile, and will pass them onto the

   103     # MRP object if it is ever created.

   104     if (defined $self->{'mrpObject'}) {

   105         $self->{'mrpObject'}->PrepareInformationForMrpFile(@mrps);

   106     }

   107     else {

   108         push @{$self->{prepareInformationForMrpFileCache}}, @mrps;

   109     }

   110 }

   111 

   112 

   113 sub Category {

   114     my $self = shift;

   115     my $path = shift;

   116 

   117     if (!$path || shift) {

   118         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";

   119     }

   120     

   121     my ($category, $errors) = $self->GetRequestedInformation($path, 'Category');

   122 

   123     if (!$category) {

   124         $category = 'X';

   125     }

   126 

   127     return ($category, $errors);

   128 }

   129 

   130 sub ExportRestricted {

   131     my $self = shift;

   132     my $path = shift;

   133 

   134     if (!$path || shift) {

   135         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";

   136     }

   137 

   138     my ($exportRestricted, $errors) = $self->GetRequestedInformation($path, 'ExportRestricted');

   139 

   140     return ($exportRestricted, $errors);

   141 }

   142 

   143 sub GetRequestedInformation {

   144     my $self = shift;

   145     my $path = shift;

   146     my $what = shift;

   147 

   148     my @errors; # This collects the errors produced from the distribution policy modules.

   149                 # The CBR Tools handle these errors in a different way.

   150 

   151     if (!$path || !$what || shift) {

   152         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";

   153     }

   154     

   155     my $result = undef;

   156     my $informationFrom = undef;

   157     

   158     if (!$self->{useDistPolFirst} && $self->{mrpObject}) {

   159         # If to use MRP files first and an Mrp object exists...

   160         $result = $self->{mrpObject}->$what($path);

   161 

   162         $informationFrom = 'M' if (defined $result);

   163     }

   164     

   165     if (! defined $result) {

   166         # If  distribution policies are to be used first or could not obtain information

   167         # from MRP object then use distribution policies

   168 

   169         # Create a distribution policy reader if one does not already exist...

   170         if (!$self->{distPolReader}) {

   171             # Create a distribution policy reader if one does not already exist...

   172             $self->{distPolReader} = Symbian::DistributionPolicy::Reader->new();

   173         }

   174         

   175         if ($self->{distPolReader}->isa("Symbian::DistributionPolicy::Reader")) {

   176             my $warner;

   177             

   178             # We may need to capture the output of the distribution policy modules

   179             if ($self->{'captureDistributionPolicyOutput'}) {

   180                 $warner = sub { push @errors, shift; };

   181             }

   182             local $SIG{__WARN__} = $warner if ($warner);

   183 

   184             # We want to make sure that we do have a reader before trying to read a file

   185             eval {  my $distPolObj = $self->{distPolReader}->ReadPolicyFile($path);

   186                     $result = $distPolObj->$what()};

   187 

   188             $informationFrom = 'D' if (defined $result);

   189         }

   190     }

   191 

   192     if ((!defined $result) && $self->{useDistPolFirst}) {

   193         # If distribution policies have been used first and failed then try getting the information from MRP files...

   194         

   195         # The Symbian::CBR::IPR::MRP might not yet have been created

   196         if (!exists $self->{mrpObject}) {

   197             $self->CreateMrpObject();

   198         }

   199         

   200         $result = $self->{mrpObject}->$what($path);

   201 

   202         $informationFrom = 'M' if (defined $result);

   203     }

   204    

   205     if (!defined $informationFrom && $self->{disallowUnclassifiedSource}) {

   206         carp "Warning: IPR information for '$path' could not be obtained from either MRP files or distribution policy files\n";

   207     }

   208         

   209     if ($self->{verbose} > 1) {

   210         # If verbose then we print information saying where the IPR information was obtained from

   211         if ($informationFrom eq 'M') {

   212             print "Info: IPR information for '$path' was obtained using MRP files\n";

   213         }

   214         elsif ($informationFrom eq 'D') {

   215             print "Info: IPR information for '$path' was obtained using Distribution Policy files\n";

   216         }        

   217     }

   218 

   219     return ($result, \@errors);

   220 }

   221 

   222 1;

   223 

   224 __END__

   225 

   226 =pod

   227 

   228 =head1 NAME

   229 

   230 Symbian::IPR - An interface to IPR information within MRP files and Distribution

   231 Policy files.

   232 

   233 =head1 SYNOPSIS

   234 

   235 use Symbian::IPR;

   236 

   237  # Instantiate a Symbian::IPR object

   238  my $iprObject = Symbian::IPR->instance(0, 0, 'MRP', undef, 1);

   239 

   240  # Get the IPR category for a path

   241  my $category = $iprObject->Category('\aPath\somewhere');

   242 

   243  # Get the export restricted flag for a path

   244  my $exportRestricted = $iprObject->ExportRestricted('\aPath\somewhere');

   245 

   246 =head1 DESCRIPTION

   247 

   248 This package provides an interface to obtaining IPR information from MRP files

   249 and Distribution Policy files.  The user can specify the order of preference

   250 between MRP and distribution policies.  If the requested information can not be

   251 obtained from the preferred choice then the package will fall back to using the

   252 other option.

   253 

   254 =head1 METHODS

   255 

   256 =head2 new(useDistPolFirst, disallowUnclassifiedSource, typeOfMrp, component, verbose)

   257 

   258 Instantiates a Symbian::IPR object.

   259 

   260 The default order is for IPR information to be obtained from MRP files first, and

   261 if unsuccessful then to obtain the IPR information from distribution policy files.

   262 If the boolean value useDistPolFirst is specified then IPR information will be

   263 obtained from distribution policy files by default, and if not successful then

   264 MRP files will be used.

   265 

   266 If the disallowUnclassifiedSource flag is specified then warnings will be produced

   267 if IPR information can not be obtained both MRP files and distribution.policy files.

   268 

   269 The typeOfMrp argument is non-optional.  Valid types are MRP and MRPDATA.  See the

   270 documentation for Symbian::CBR::MRP::Reader for more information.

   271 

   272 If a component had been specified then the MRP file for the component will be processed

   273 and the IPR information obtained.  Any MRP files for dependant components will be

   274 located and processed too.  If no component name has been specified all MRP files

   275 in the environment will be processed.

   276 

   277 =head2 Category(path)

   278 

   279 Returns the IPR category of the path.  If no IPR information exists for the

   280 specified path then X will be returned.

   281 

   282 =head2 ExportRestricted(path)

   283 

   284 Returns true if the specified path is export restricted, and false if it is not.

   285 If no IPR information exists for the specified path then undef will be returned.

   286 

   287 =head2 PrepareInformationForComponent(component_name)

   288 

   289 If using MRP files for IPR information it is possible to specify which components

   290 contain the information required.  This improves performance as only required

   291 MRP files are processed.  The default behaviour is to process all MRP files listed

   292 in the CBR Tools environment database.

   293 

   294 If using distribution policy files as default then information passed to this method

   295 will be cached and realised only if it becomes necessary to use MRP files for IPR

   296 information (e.g. distribution policy file does not exist).

   297 

   298 =head2 PrepareInformationForMrpFile(list_of_mrp_files)

   299 

   300 If using MRP files for IPR information it is possible to specify which MRP files

   301 contain the information required.  This can be used in scenarios where a CBR Tools

   302 environment database does not exist, and so MRP locations are unknown.

   303 

   304 If using distribution policy files as default then information passed to this method

   305 will be cached and realised only if it becomes necessary to use MRP files for IPR

   306 information (e.g. distribution policy file does not exist).

   307 

   308 =head1 COPYRIGHT

   309 

   310  Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

   311  All rights reserved.

   312  This component and the accompanying materials are made available

   313  under the terms of the License "Eclipse Public License v1.0"

   314  which accompanies this distribution, and is available

   315  at the URL "http://www.eclipse.org/legal/epl-v10.html".

   316  

   317  Initial Contributors:

   318  Nokia Corporation - initial contribution.

   319  

   320  Contributors:

   321  

   322  Description:

   323  

   324 

   325 =cut