# 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