1 # Copyright (c) 2005-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 

    17 package Symbian::DistributionPolicy;

    18 use strict;

    19 

    20 use POSIX qw(mktime);

    21 

    22 # create OSD bit vector constants for $obj->{osd}

    23 use constant SYMBIAN_DPOL_COMMON      => 0x0001;

    24 use constant SYMBIAN_DPOL_OPTIONAL    => 0x0002;

    25 use constant SYMBIAN_DPOL_SYMBIAN     => 0x0004;

    26 use constant SYMBIAN_DPOL_REPLACEABLE => 0x0008;

    27 use constant SYMBIAN_DPOL_TEST        => 0x0010;

    28 

    29 sub new {

    30     my $class = shift;

    31     my $self = {

    32         authorized        => {},

    33         category          => undef,

    34         description       => '',

    35         expires           => undef,

    36         export_restricted => undef,

    37         osd               => 0,

    38     };

    39     bless $self, $class;

    40     return $self;

    41 }

    42 

    43 # public.

    44 

    45 sub Authorized {

    46     my $self = shift;

    47     my $licensee = shift;

    48     my $time = @_ ? shift : time; # use current time if not specified

    49     # absent = fail

    50     return if !exists $self->{authorized}{$licensee};

    51     # present without expiry = pass

    52     return 1 if !defined $self->{authorized}{$licensee};

    53     # check expiry

    54     return $self->{authorized}{$licensee} > $time;

    55 }

    56 

    57 sub SetAuthorizedUntil {

    58     my $self = shift;

    59     my $licensee = shift;

    60     my $until = shift;

    61     return if !defined $licensee;

    62     $self->{authorized}{$licensee} = $self->parsedate($until);

    63     # success depends on whether a date was passed and parsed successfully

    64     return defined $until ? defined $self->{authorized}{$licensee} : 1;

    65 }

    66 

    67 sub Category {

    68     return $_[0]->{category};

    69 }

    70 

    71 sub SetCategory {

    72     my $self = shift;

    73     my $cat = uc(shift); # uppercase

    74     return if !defined $cat;

    75     if ($cat !~ /^[A-Z]$/) {

    76         warn "Invalid IPR category: '$cat'\n";

    77         return;

    78     }

    79     $self->{category} = $cat;

    80     return 1;

    81 }

    82 

    83 sub Common {

    84     return $_[0]->{osd} & SYMBIAN_DPOL_COMMON;

    85 }

    86 

    87 sub SetCommon {

    88     my $self = shift;

    89     my $bool = shift;

    90     return $self->SetOptional(1) if !$bool;

    91     $self->{osd} |= SYMBIAN_DPOL_COMMON;

    92     $self->{osd} &= ~SYMBIAN_DPOL_OPTIONAL; # toggles optional off

    93     return 1;

    94 }

    95 

    96 sub Description {

    97     return $_[0]->{description};

    98 }

    99 

   100 sub SetDescription {

   101     my $self = shift;

   102     my $desc = shift;

   103     $self->{description} = defined $desc ? $desc : '';

   104     return 1;

   105 }

   106 

   107 sub Expires {

   108     return $_[0]->{expires};

   109 }

   110 

   111 sub SetExpires {

   112     my $self = shift;

   113     my $date = shift;

   114     return if !defined $date;

   115     $self->{expires} = $self->parsedate($date);

   116     # if parsedate failed it returned undef so that is our status

   117     return defined $self->{expires};

   118 }

   119 

   120 sub Expired {

   121     my $self = shift;

   122     my $time = @_ ? shift : time;

   123     # not defined = no expiry

   124     return if !defined $self->{expires};

   125     # check expiry

   126     return $self->{expires} < $time;

   127 }

   128 

   129 sub ExportRestricted {

   130     my $self = shift;

   131     

   132     # If the category is defined then we know a distribution policy file has been parsed.

   133     if ($self->{category}) {

   134         # double ! reduces the value to a boolean

   135         return !!$self->{export_restricted};

   136     }

   137     return undef;

   138 }

   139 

   140 sub SetExportRestricted {

   141     my $self = shift;

   142     my $flag = shift;

   143     $self->{export_restricted} = $flag;

   144     return 1;

   145 }

   146 

   147 sub Optional {

   148     return $_[0]->{osd} & SYMBIAN_DPOL_OPTIONAL;

   149 }

   150 

   151 sub SetOptional {

   152     my $self = shift;

   153     my $bool = shift;

   154     return $self->SetCommon(1) if !$bool;

   155     $self->{osd} |= SYMBIAN_DPOL_OPTIONAL;

   156     $self->{osd} &= ~SYMBIAN_DPOL_COMMON; # toggles common off

   157     return 1;

   158 }

   159 

   160 sub Replaceable {

   161     return $_[0]->{osd} & SYMBIAN_DPOL_REPLACEABLE;

   162 }

   163 

   164 sub SetReplaceable {

   165     my $self = shift;

   166     my $bool = shift;

   167     return $self->SetSymbian(1) if !$bool;

   168     $self->{osd} |= SYMBIAN_DPOL_REPLACEABLE;

   169     $self->{osd} &= ~SYMBIAN_DPOL_SYMBIAN; # toggles symbian off

   170     return 1;

   171 }

   172 

   173 sub Symbian {

   174     return $_[0]->{osd} & SYMBIAN_DPOL_SYMBIAN;

   175 }

   176 

   177 sub SetSymbian {

   178     my $self = shift;

   179     my $bool = shift;

   180     return $self->SetReplaceable(1) if !$bool;

   181     $self->{osd} |= SYMBIAN_DPOL_SYMBIAN;

   182     $self->{osd} &= ~SYMBIAN_DPOL_REPLACEABLE; # toggles replaceable off

   183     return 1;

   184 }

   185 

   186 sub Test {

   187     return $_[0]->{osd} & SYMBIAN_DPOL_TEST;

   188 }

   189 

   190 sub SetTest {

   191     my $self = shift;

   192     my $bool = shift;

   193     if ($bool) {

   194         $self->{osd} |= SYMBIAN_DPOL_TEST; # on

   195     } else {

   196         $self->{osd} &= ~SYMBIAN_DPOL_TEST; # off

   197     }

   198     return 1;

   199 }

   200 

   201 # private.

   202 

   203 sub parsedate {

   204     my $self = shift;

   205     my $date = shift; # dd/mm/yyyy

   206     return unless defined $date;

   207     if ($date !~ m!^(\d\d)/(\d\d)/(\d{4})$!) {

   208         warn "Invalid date: '$date'\n";

   209         return;

   210     }

   211     my($d, $m, $y) = ($1, $2, $3);

   212     my $time = mktime(59, 59, 23, $d, --$m, $y-1900);

   213     if (!defined $time) {

   214         warn "Date out of range: '$date'\n";

   215         return;

   216     }

   217     return $time;

   218 }

   219 

   220 1;

   221 

   222 =pod

   223 

   224 =head1 NAME

   225 

   226 Symbian::DistributionPolicy - OO representation of a DISTRIBUTION.POLICY file.

   227 

   228 =head1 SYNOPSIS

   229 

   230  # normally you would not create a policy object directly but

   231  # use one returned by the Symbian::DistributionPolicy::Reader...

   232 

   233  use Symbian::DistributionPolicy::Reader;

   234 

   235  my $dpr = Symbian::DistributionPolicy::Reader->new();

   236 

   237  my $policy = $dpr->ReadPolicyFile($path);

   238 

   239  # then you may query the object using the methods below

   240 

   241 =head1 DESCRIPTION

   242 

   243 This module provides an object to represent the data in a DISTRIBUTION.POLICY

   244 file. The DISTRIBUTION.POLICY file specifies the policy information for all the

   245 source code files in the same directory. The directives are:

   246 

   247 =head2 Authorized LICENSEE_ID [until DATE]

   248 

   249 The C<Authorized> directive overrides any IPR restriction and makes available

   250 the source to the licensee with a specific I<LICENSEE_ID>. If the C<until>

   251 keyword is used then I<DATE> should be a string in the format dd/mm/yyyy. The

   252 exception made by this directive will expire at the end of this date. Only

   253 one C<Authorized> directive is allowed per I<LICENSEE_ID>.

   254 

   255 =head2 Category IPR_CATEGORY

   256 

   257 The C<Category> directive specifies the IPR category of the source.

   258 I<IPR_CATEGORY> may be any single character from the range A to Z. The default for

   259 unclassified source is X.

   260 

   261 =head2 Description TEXT

   262 

   263 The C<Description> directive specifies a one-line textual description of the

   264 directory content. I<TEXT> need not be quoted (in fact, it should not be).

   265 

   266 =head2 Expires DATE

   267 

   268 The C<Expires> directive specifies the date after which the directive(s) in the

   269 DISTRIBUTION.POLICY file become invalid. I<DATE> must be in dd/mm/yyyy format.

   270 

   271 =head2 Export STATUS

   272 

   273 The C<Export> keyword specifies whether the source is export restricted or not.

   274 The default is that it is not and this is equivalent to setting I<STATUS> to

   275 Unrestricted. Changing I<STATUS> to Restricted will enable this feature.

   276 

   277 =head2 OSD: ((COMMON|OPTIONAL) (SYMBIAN|REPLACEABLE)|REFERENCE/TEST) [NAME]

   278 

   279 The OSD line describes the nature of the source in five metrics: (COMMON vs.

   280 OPTIONAL and SYMBIAN vs. REPLACEABLE) or REFERENCE/TEST. The descriptions of

   281 these are available in Schedule 2 of the CKL.

   282 

   283 =head1 METHODS

   284 

   285 In addition to the constructor, getters and setters are provided for all policy

   286 directives:

   287 

   288 =begin text

   289 

   290     +--------------+-------------------+----------------------+

   291     | Directive    | Getter            | Setter               |

   292     +--------------+-------------------+----------------------+

   293     | Authorized   | Authorized        | SetAuthorizedUntil   |

   294     | Category     | Category          | SetCategory          |

   295     | Description  | Description       | SetDescription       |

   296     | Expires      | Expires           | SetExpires           |

   297     | Export       | ExportRestricted  | SetExportRestricted  |

   298     | OSD          | See table below for individual methods.  |

   299     +--------------+-------------------+----------------------+

   300 

   301 =end

   302 

   303 Individual OSD metrics getters and setters are detailed in the following table:

   304 

   305 =begin text

   306 

   307     +-----------------+--------------+-----------------+

   308     | Metric          | Getter       | Setter          |

   309     +-----------------+--------------+-----------------+

   310     | COMMON          | Common       | SetCommon       |

   311     | OPTIONAL        | Optional     | SetOptional     |

   312     | REPLACEABLE     | Replaceable  | SetReplaceable  |

   313     | SYMBIAN         | Symbian      | SetSymbian      |

   314     | REFERENCE/TEST  | Test         | SetTest         |

   315     +-----------------+--------------+-----------------+

   316 

   317 =end

   318 

   319 =head2 new()

   320 

   321 Creates the policy object with default settings (cat=X, desc='', expires=never,

   322 export=unrestricted).

   323 

   324 =head2 Authorized($licensee_id[, $time])

   325 

   326 Returns the authorized status as a boolean (1=authorized, undef=not) for a

   327 given $licensee_id. If a $time is not specified the current time will be used.

   328 This is required if the C<Authorized> directive makes use of the I<until>

   329 keyword and the expiry time needs to be checked.

   330 

   331 =head2 SetAuthorizedUntil($licensee_id[, $date])

   332 

   333 Adds an authorized licensee to the policy. If an expiry date is specified it

   334 must be in dd/mm/yyyy format.

   335 

   336 =head2 Category()

   337 

   338 Returns the IPR category as a single-character string. If no IPR category exists

   339 in the distrubution file then 'undef' will be returned.

   340 

   341 =head2 SetCategory($cat)

   342 

   343 Sets the category. Will accept any single character from the range A to Z as a

   344 string in $cat.

   345 

   346 =head2 Common()

   347 

   348 Returns non-zero if the OSD metric COMMON is set.

   349 

   350 =head2 SetCommon($bool)

   351 

   352 Sets the OSD metric COMMON if $bool is true. Unsets it if $bool is false. Also

   353 sets the mutually exclusive OPTIONAL to the opposite.

   354 

   355 =head2 Description()

   356 

   357 Returns the description text (never undef - if blank you get an empty string).

   358 

   359 =head2 SetDescription($text)

   360 

   361 Sets the description text.

   362 

   363 =head2 Expires()

   364 

   365 Returns the expiry time specified in the file (or undef if not specified). It

   366 will be in UNIX (epoch) time format for your convenience. See Expired().

   367 

   368 =head2 SetExpires($date)

   369 

   370 Sets the expiry time to 23:59:59 on the date provided. $date should be a string

   371 in dd/mm/yyyy format.

   372 

   373 =head2 Expired([$time])

   374 

   375 Will test whether the policy data has (or will have) expired at the time

   376 specified. If no time is specified, the current time will be used - i.e. to

   377 determine whether the policy has already expired.

   378 

   379 =head2 ExportRestricted()

   380 

   381 Returns the export restricted status as a boolean (1=restricted,

   382 0=unrestricted, undef=information not available).

   383 

   384 =head2 SetExportRestricted($flag)

   385 

   386 Sets the export restricted status. $flag is a boolean (undef is allowed for

   387 false).

   388 

   389 =head2 Optional()

   390 

   391 Returns non-zero if the OSD metric OPTIONAL is set.

   392 

   393 =head2 SetOptional($bool)

   394 

   395 Sets the OSD metric OPTIONAL if $bool is true. Unsets it if $bool is false. Also

   396 sets the mutually exclusive COMMON to the opposite.

   397 

   398 =head2 Replaceable()

   399 

   400 Returns non-zero if the OSD metric REPLACEABLE is set.

   401 

   402 =head2 SetReplaceable($bool)

   403 

   404 Sets the OSD metric REPLACEABLE if $bool is true. Unsets it if $bool is false.

   405 Also sets the mutually exclusive SYMBIAN to the opposite.

   406 

   407 =head2 Symbian()

   408 

   409 Returns non-zero if the OSD metric SYMBIAN is set.

   410 

   411 =head2 SetSymbian($bool)

   412 

   413 Sets the OSD metric SYMBIAN if $bool is true. Unsets it if $bool is false. Also

   414 sets the mutually exclusive REPLACEABLE to the opposite.

   415 

   416 =head2 Test()

   417 

   418 Returns non-zero if the OSD metric REFERENCE/TEST is set.

   419 

   420 =head2 SetTest($bool)

   421 

   422 Sets the OSD metric REFERENCE/TEST if $bool is true. Unsets it if $bool is

   423 false.

   424 

   425 =head1 SEE ALSO

   426 

   427 L<Symbian::DistributionPolicy::Reader> to see how to get your $policy object(s).

   428 

   429 =head1 COPYRIGHT

   430 

   431  Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

   432  All rights reserved.

   433  This component and the accompanying materials are made available

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

   435  which accompanies this distribution, and is available

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

   437  

   438  Initial Contributors:

   439  Nokia Corporation - initial contribution.

   440  

   441  Contributors:

   442  

   443  Description:

   444  

   445 

   446 =cut