--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/releasing/cbrtools/perl/Symbian/IPR.pm Fri Jun 25 18:37:20 2010 +0800
@@ -0,0 +1,325 @@
+# Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+# All rights reserved.
+# This component and the accompanying materials are made available
+# under the terms of the License "Eclipse Public License v1.0"
+# which accompanies this distribution, and is available
+# at the URL "http://www.eclipse.org/legal/epl-v10.html".
+#
+# Initial Contributors:
+# Nokia Corporation - initial contribution.
+#
+# Contributors:
+#
+# Description:
+#
+#
+# Description:
+# Symbian::IPR
+#
+
+package Symbian::IPR;
+
+use strict;
+use Carp;
+use Symbian::CBR::IPR::MRP;
+use Symbian::DistributionPolicy::Reader;
+
+use base qw(Class::Singleton);
+
+
+sub _new_instance {
+ my $pkg = shift;
+ my $useDistPolFirst = shift;
+ my $disallowUnclassifiedSource = shift;
+ my $typeOfMrp = shift;
+ my $verbose = shift;
+ my $captureDistributionPolicyOutput = shift;
+
+ if (!$typeOfMrp || shift) {
+ # caller(0))[3] gives the package and the method called, e.g. Symbian::IPR::_new_instance
+ croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+ }
+
+ my $self = {
+ 'useDistPolFirst' => $useDistPolFirst,
+ 'disallowUnclassifiedSource' => $disallowUnclassifiedSource,
+ 'verbose' => $verbose,
+ 'typeOfMrp' => $typeOfMrp,
+ 'captureDistributionPolicyOutput' => $captureDistributionPolicyOutput};
+
+ bless $self, $pkg;
+
+ if (!$useDistPolFirst) {
+ # If we are not using distribution policy files as default then create a Symbian::CBR::IPR::MRP object...
+ $self->CreateMrpObject();
+ }
+
+ return $self;
+}
+
+sub CreateMrpObject {
+ my $self = shift;
+
+ if (!exists $self->{'mrpObject'}) {
+ $self->{'mrpObject'} = Symbian::CBR::IPR::MRP->instance($self->{typeOfMrp}, $self->{verbose});
+ }
+
+ # We may have cached calls to PrepareInformationForComponent...
+ if (defined $self->{prepareInformationForComponentCache}) {
+ foreach my $component (@{$self->{prepareInformationForComponentCache}}) {
+ $self->PrepareInformationForComponent($component);
+ }
+ delete $self->{prepareInformationForComponentCache};
+ }
+
+ # and also to PrepareInformationForMrpFile...
+ if (defined $self->{prepareInformationForMrpFileCache}) {
+ $self->PrepareInformationForMrpFile->(@{$self->{prepareInformationForMrpFileCache}});
+ delete $self->{prepareInformationForMrpFileCache};
+ }
+}
+
+sub PrepareInformationForComponent {
+ my $self = shift;
+ my $component = shift;
+
+ # An MRP object may not have been created, for example if using distribution policy files first.
+ # In that case we cache the calls to PrepareInformationForComponent, and will pass them onto the
+ # MRP object if it is ever created.
+ if (defined $self->{'mrpObject'}) {
+ $self->{'mrpObject'}->PrepareInformationForComponent($component);
+ }
+ else {
+ push @{$self->{prepareInformationForComponentCache}}, $component;
+ }
+}
+
+sub PrepareInformationForMrpFile {
+ my $self = shift;
+ my @mrps = shift;
+
+ # An MRP object may not have been created, for example if using distribution policy files first.
+ # In that case we cache the calls to PrepareInformationForMrpFile, and will pass them onto the
+ # MRP object if it is ever created.
+ if (defined $self->{'mrpObject'}) {
+ $self->{'mrpObject'}->PrepareInformationForMrpFile(@mrps);
+ }
+ else {
+ push @{$self->{prepareInformationForMrpFileCache}}, @mrps;
+ }
+}
+
+
+sub Category {
+ my $self = shift;
+ my $path = shift;
+
+ if (!$path || shift) {
+ croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+ }
+
+ my ($category, $errors) = $self->GetRequestedInformation($path, 'Category');
+
+ if (!$category) {
+ $category = 'X';
+ }
+
+ return ($category, $errors);
+}
+
+sub ExportRestricted {
+ my $self = shift;
+ my $path = shift;
+
+ if (!$path || shift) {
+ croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+ }
+
+ my ($exportRestricted, $errors) = $self->GetRequestedInformation($path, 'ExportRestricted');
+
+ return ($exportRestricted, $errors);
+}
+
+sub GetRequestedInformation {
+ my $self = shift;
+ my $path = shift;
+ my $what = shift;
+
+ my @errors; # This collects the errors produced from the distribution policy modules.
+ # The CBR Tools handle these errors in a different way.
+
+ if (!$path || !$what || shift) {
+ croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+ }
+
+ my $result = undef;
+ my $informationFrom = undef;
+
+ if (!$self->{useDistPolFirst} && $self->{mrpObject}) {
+ # If to use MRP files first and an Mrp object exists...
+ $result = $self->{mrpObject}->$what($path);
+
+ $informationFrom = 'M' if (defined $result);
+ }
+
+ if (! defined $result) {
+ # If distribution policies are to be used first or could not obtain information
+ # from MRP object then use distribution policies
+
+ # Create a distribution policy reader if one does not already exist...
+ if (!$self->{distPolReader}) {
+ # Create a distribution policy reader if one does not already exist...
+ $self->{distPolReader} = Symbian::DistributionPolicy::Reader->new();
+ }
+
+ if ($self->{distPolReader}->isa("Symbian::DistributionPolicy::Reader")) {
+ my $warner;
+
+ # We may need to capture the output of the distribution policy modules
+ if ($self->{'captureDistributionPolicyOutput'}) {
+ $warner = sub { push @errors, shift; };
+ }
+ local $SIG{__WARN__} = $warner if ($warner);
+
+ # We want to make sure that we do have a reader before trying to read a file
+ eval { my $distPolObj = $self->{distPolReader}->ReadPolicyFile($path);
+ $result = $distPolObj->$what()};
+
+ $informationFrom = 'D' if (defined $result);
+ }
+ }
+
+ if ((!defined $result) && $self->{useDistPolFirst}) {
+ # If distribution policies have been used first and failed then try getting the information from MRP files...
+
+ # The Symbian::CBR::IPR::MRP might not yet have been created
+ if (!exists $self->{mrpObject}) {
+ $self->CreateMrpObject();
+ }
+
+ $result = $self->{mrpObject}->$what($path);
+
+ $informationFrom = 'M' if (defined $result);
+ }
+
+ if (!defined $informationFrom && $self->{disallowUnclassifiedSource}) {
+ carp "Warning: IPR information for '$path' could not be obtained from either MRP files or distribution policy files\n";
+ }
+
+ if ($self->{verbose} > 1) {
+ # If verbose then we print information saying where the IPR information was obtained from
+ if ($informationFrom eq 'M') {
+ print "Info: IPR information for '$path' was obtained using MRP files\n";
+ }
+ elsif ($informationFrom eq 'D') {
+ print "Info: IPR information for '$path' was obtained using Distribution Policy files\n";
+ }
+ }
+
+ return ($result, \@errors);
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Symbian::IPR - An interface to IPR information within MRP files and Distribution
+Policy files.
+
+=head1 SYNOPSIS
+
+use Symbian::IPR;
+
+ # Instantiate a Symbian::IPR object
+ my $iprObject = Symbian::IPR->instance(0, 0, 'MRP', undef, 1);
+
+ # Get the IPR category for a path
+ my $category = $iprObject->Category('\aPath\somewhere');
+
+ # Get the export restricted flag for a path
+ my $exportRestricted = $iprObject->ExportRestricted('\aPath\somewhere');
+
+=head1 DESCRIPTION
+
+This package provides an interface to obtaining IPR information from MRP files
+and Distribution Policy files. The user can specify the order of preference
+between MRP and distribution policies. If the requested information can not be
+obtained from the preferred choice then the package will fall back to using the
+other option.
+
+=head1 METHODS
+
+=head2 new(useDistPolFirst, disallowUnclassifiedSource, typeOfMrp, component, verbose)
+
+Instantiates a Symbian::IPR object.
+
+The default order is for IPR information to be obtained from MRP files first, and
+if unsuccessful then to obtain the IPR information from distribution policy files.
+If the boolean value useDistPolFirst is specified then IPR information will be
+obtained from distribution policy files by default, and if not successful then
+MRP files will be used.
+
+If the disallowUnclassifiedSource flag is specified then warnings will be produced
+if IPR information can not be obtained both MRP files and distribution.policy files.
+
+The typeOfMrp argument is non-optional. Valid types are MRP and MRPDATA. See the
+documentation for Symbian::CBR::MRP::Reader for more information.
+
+If a component had been specified then the MRP file for the component will be processed
+and the IPR information obtained. Any MRP files for dependant components will be
+located and processed too. If no component name has been specified all MRP files
+in the environment will be processed.
+
+=head2 Category(path)
+
+Returns the IPR category of the path. If no IPR information exists for the
+specified path then X will be returned.
+
+=head2 ExportRestricted(path)
+
+Returns true if the specified path is export restricted, and false if it is not.
+If no IPR information exists for the specified path then undef will be returned.
+
+=head2 PrepareInformationForComponent(component_name)
+
+If using MRP files for IPR information it is possible to specify which components
+contain the information required. This improves performance as only required
+MRP files are processed. The default behaviour is to process all MRP files listed
+in the CBR Tools environment database.
+
+If using distribution policy files as default then information passed to this method
+will be cached and realised only if it becomes necessary to use MRP files for IPR
+information (e.g. distribution policy file does not exist).
+
+=head2 PrepareInformationForMrpFile(list_of_mrp_files)
+
+If using MRP files for IPR information it is possible to specify which MRP files
+contain the information required. This can be used in scenarios where a CBR Tools
+environment database does not exist, and so MRP locations are unknown.
+
+If using distribution policy files as default then information passed to this method
+will be cached and realised only if it becomes necessary to use MRP files for IPR
+information (e.g. distribution policy file does not exist).
+
+=head1 COPYRIGHT
+
+ Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+ All rights reserved.
+ This component and the accompanying materials are made available
+ under the terms of the License "Eclipse Public License v1.0"
+ which accompanies this distribution, and is available
+ at the URL "http://www.eclipse.org/legal/epl-v10.html".
+
+ Initial Contributors:
+ Nokia Corporation - initial contribution.
+
+ Contributors:
+
+ Description:
+
+
+=cut