1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/featuremgmt/featuremgr/tools/datfilehelpers/FMCreate.pm Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,529 @@
1.4 +#!perl -w
1.5 +# Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +# All rights reserved.
1.7 +# This component and the accompanying materials are made available
1.8 +# under the terms of "Eclipse Public License v1.0"
1.9 +# which accompanies this distribution, and is available
1.10 +# at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +#
1.12 +# Initial Contributors:
1.13 +# Nokia Corporation - initial contribution.
1.14 +#
1.15 +# Contributors:
1.16 +#
1.17 +# Description:
1.18 +#
1.19 +
1.20 +use strict;
1.21 +
1.22 +#
1.23 +# Perl module to create and maintain feature manager data files.
1.24 +# You can either set up the information programmatically or else load up
1.25 +# information from a pre-existing feature data file and then modify it. You
1.26 +# can also save the information to a file (in feature manager dataset format).
1.27 +#
1.28 +# This class maintains header information plus two arrays, one containing
1.29 +# feature flag information and the other containing default supported range
1.30 +# information. Those are themselves objects and have their own accessor
1.31 +# methods.
1.32 +#
1.33 +
1.34 +package FMCreate;
1.35 +
1.36 +use featureflag;
1.37 +use featuredsr;
1.38 +
1.39 +#
1.40 +# n e w
1.41 +#
1.42 +# Create a new FMCreate object. For example 'my $fmc = FMCreate->new();
1.43 +#
1.44 +sub new
1.45 +{
1.46 + my $arg = shift;
1.47 + my $class = ref($arg) || $arg;
1.48 + my $self = {
1.49 + typefield => "feat", # 4 bytes wide.
1.50 + fileversion => 1, # 2 bytes.
1.51 + fileflags => 0, # 2 bytes.
1.52 + numfeatures => 0, # 4 bytes. (this is 'x')
1.53 + numdefuid => 0, # 4 bytes. (this is 'y')
1.54 + endian => "LE",
1.55 + packprefix => "V", # Changed with endian-ness.
1.56 + # Used to create binary strings.
1.57 +
1.58 + featureflags => [], # There are x of these.
1.59 + dsrs => [], # There are y of these.
1.60 + };
1.61 + bless $self, $class;
1.62 + return $self;
1.63 +}
1.64 +
1.65 +# Print to STDOUT the header information, feature flags information and
1.66 +# default supported range information.
1.67 +sub ShowALL
1.68 +{
1.69 + my $self = shift;
1.70 + return undef unless(ref($self));
1.71 + $self->ShowHeader();
1.72 + $self->ShowFeatureFlags();
1.73 + $self->ShowDSRs();
1.74 + return 1;
1.75 +}
1.76 +
1.77 +# Print to STDOUT the header information we have.
1.78 +sub ShowHeader
1.79 +{
1.80 + my $self = shift;
1.81 + return undef unless(ref($self));
1.82 +
1.83 + # Get header information..
1.84 + my $typefield = $self->TypeField();
1.85 + my $fileversion = $self->FileVersion();
1.86 + my $fileflags = $self->FileFlags();
1.87 + my $numfeatures = $self->NumFeatures();
1.88 + my $numdefuid = $self->NumDefUid();
1.89 +
1.90 + # Display it in English.
1.91 + print "TYPEFIELD: '$typefield'\n";
1.92 + print "FILEVERSION: '$fileversion'\n";
1.93 + print "FILEFLAGS: '$fileflags'\n";
1.94 + print "NUMFEATURES: '$numfeatures'\n";
1.95 + print "NUMDSRS: '$numdefuid'\n";
1.96 +
1.97 + return(1);
1.98 +}
1.99 +
1.100 +# Call the 'Show' method in each of the feature flag objects we
1.101 +# have - this will print their content to STDOUT.
1.102 +sub ShowFeatureFlags
1.103 +{
1.104 + my $self = shift;
1.105 + return undef unless(ref($self));
1.106 + my $ffs = $self->FeatureFlags;
1.107 + return 1 unless(@$ffs);
1.108 +
1.109 + print "\nFeature Flags\n";
1.110 + print "=============\n";
1.111 + for my $ff (@$ffs)
1.112 + {
1.113 + $ff->Show();
1.114 + }
1.115 + return 1;
1.116 +}
1.117 +
1.118 +# Call the 'Show' method in each of the default supported range objects we
1.119 +# have - this will print their content to STDOUT.
1.120 +sub ShowDSRs
1.121 +{
1.122 + my $self = shift;
1.123 + return undef unless(ref($self));
1.124 + my $fds = $self->FeatureDSRs;
1.125 + return 1 unless(@$fds);
1.126 + print "\nFeature DSRs\n";
1.127 + print "============\n";
1.128 + for my $fd (@$fds)
1.129 + {
1.130 + $fd->Show();
1.131 + }
1.132 + return 1;
1.133 +}
1.134 +
1.135 +# Get/Set the endian-ness we want. Changes the 'packprefix' member which is
1.136 +# used in the creation of binary data.
1.137 +sub Endian
1.138 +{
1.139 + my $self = shift;
1.140 + return undef unless(ref($self));
1.141 + my $arg = shift;
1.142 + return $self->{endian} unless(defined($arg));
1.143 + if($arg =~ m/(LE|BE)/i)
1.144 + {
1.145 + my $endian = uc($1);
1.146 + $self->{endian} = $endian;
1.147 + # Used by 'pack' to generate binary strings.
1.148 + $self->{packprefix} = "V" if($endian eq "LE");
1.149 + $self->{packprefix} = "N" if($endian eq "BE");
1.150 + }
1.151 + return $self->{endian};
1.152 +}
1.153 +
1.154 +# This is 'feat'.
1.155 +sub TypeField
1.156 +{
1.157 + my $self = shift;
1.158 + return undef unless(ref($self));
1.159 + my $arg = shift;
1.160 + $self->{typefield} = $arg if(defined($arg));
1.161 + return $self->{typefield};
1.162 +}
1.163 +
1.164 +sub FileVersion
1.165 +{
1.166 + my $self = shift;
1.167 + return undef unless(ref($self));
1.168 + my $arg = shift;
1.169 + # Should we be testing for a numeric value?
1.170 + $self->{fileversion} = $arg if(defined($arg));
1.171 + return $self->{fileversion};
1.172 +}
1.173 +
1.174 +sub FileFlags
1.175 +{
1.176 + my $self = shift;
1.177 + return undef unless(ref($self));
1.178 + my $arg = shift;
1.179 + $self->{fileflags} = $arg if(defined($arg));
1.180 + return $self->{fileflags};
1.181 +}
1.182 +
1.183 +# How many feature flag objects have we got?
1.184 +sub NumFeatures
1.185 +{
1.186 + my $self = shift;
1.187 + return undef unless(ref($self));
1.188 + my $arg = shift;
1.189 + $self->{numfeatures} = $arg if(defined($arg));
1.190 + return $self->{numfeatures};
1.191 +}
1.192 +
1.193 +# How many default supported range objects have we got?
1.194 +sub NumDefUid
1.195 +{
1.196 + my $self = shift;
1.197 + return undef unless(ref($self));
1.198 + my $arg = shift;
1.199 + $self->{numdefuid} = $arg if(defined($arg));
1.200 + return $self->{numdefuid};
1.201 +}
1.202 +
1.203 +# Create a binary string containing the header information for the
1.204 +# feature manager data file based on the various fields in this object.
1.205 +sub CreateBinaryHeader
1.206 +{
1.207 + my $self = shift;
1.208 + return undef unless(ref($self));
1.209 + my $hdrstring;
1.210 +
1.211 + # Get the letter for packing information with 'pack' into a binary form.
1.212 + my $pack16 = lc($self->{packprefix});
1.213 + my $pack32 = uc($self->{packprefix});
1.214 +
1.215 + # Get header information..
1.216 + my $typefield = $self->TypeField();
1.217 + my $fileversion = $self->FileVersion();
1.218 + my $fileflags = $self->FileFlags();
1.219 + my $numfeatures = $self->NumFeatures();
1.220 + my $numdefuid = $self->NumDefUid();
1.221 +
1.222 + # Write the 'type' field out. This is 'feat'. Would this be different on
1.223 + # big-endian systems?
1.224 + $hdrstring = $typefield;
1.225 +
1.226 + # Now the file version number. A 16-bit value.. Will this cause trouble
1.227 + # if the shifted value is signed?
1.228 + $hdrstring .= pack($pack16 . "1", $fileversion);
1.229 +
1.230 + # Now the file flags. Another 16-bit value..
1.231 + $hdrstring .= pack($pack16 . "1", $fileflags);
1.232 +
1.233 + # Now the number of listed features - a 32-bit value.
1.234 + $hdrstring .= pack($pack32 . "1", $numfeatures);
1.235 +
1.236 + # Now the number of listed features - a 32-bit value.
1.237 + $hdrstring .= pack($pack32 . "1", $numdefuid);
1.238 +
1.239 + return $hdrstring;
1.240 +}
1.241 +
1.242 +# Writes the binary file specified as an argument with the content of this
1.243 +# and contained feature flag and dsr objects.
1.244 +sub WriteToFile
1.245 +{
1.246 + my $self = shift;
1.247 + return undef unless(ref($self));
1.248 + my $file = shift;
1.249 + return undef unless(defined($file));
1.250 + open FILE, "> $file" or die "Couldn't open file '$file' for writing.\n";
1.251 + binmode FILE;
1.252 + print FILE $self->BinaryContent();
1.253 + close FILE;
1.254 + return 1;
1.255 +}
1.256 +
1.257 +
1.258 +# Create the binary equivalent of the internal data and return it as a
1.259 +# string.
1.260 +sub BinaryContent
1.261 +{
1.262 + my $self = shift;
1.263 + return undef unless(ref($self));
1.264 +
1.265 + # First get the header information for the registry manager data file.
1.266 + my $ret = $self->CreateBinaryHeader();
1.267 +
1.268 + # Get the feature flag entries.. This is an array reference.
1.269 + # For each one append the binary representation of the information
1.270 + # contained.
1.271 + my $ffs = $self->FeatureFlags;
1.272 + for my $ff (@$ffs)
1.273 + {
1.274 + $ret .= $ff->BinaryContent();
1.275 + }
1.276 +
1.277 + # Get the feature default supported range entries.. This is an array
1.278 + # reference too. For each one append the binary representation of
1.279 + # uid range contained.
1.280 + my $fdsrs = $self->FeatureDSRs;
1.281 + for my $ff (@$fdsrs)
1.282 + {
1.283 + $ret .= $ff->BinaryContent();
1.284 + }
1.285 + return $ret;
1.286 +}
1.287 +
1.288 +# Return a reference to the 'feature flags' array.
1.289 +sub FeatureFlags
1.290 +{
1.291 + my $self = shift;
1.292 + return undef unless(ref($self));
1.293 + return $self->{featureflags};
1.294 +}
1.295 +
1.296 +# Add a Feature Flag object. Perhaps there should be code to check if we
1.297 +# already know about this feature flag. (i.e check the uid against the ones
1.298 +# we have).
1.299 +sub AddFeatureFlag
1.300 +{
1.301 + my $self = shift;
1.302 + return undef unless(ref($self));
1.303 + my $arg = shift;
1.304 + die "Method 'AddFeatureFlag' requires a 'FeatureFlag' object as argument.\n"
1.305 + unless(ref($arg) eq "FeatureFlag");
1.306 + push @{$self->FeatureFlags()}, $arg;
1.307 + $self->NumFeatures($self->NumFeatures() + 1);
1.308 + return 1;
1.309 +}
1.310 +
1.311 +# Return a reference to the 'feature dsrs' array.
1.312 +sub FeatureDSRs
1.313 +{
1.314 + my $self = shift;
1.315 + return undef unless(ref($self));
1.316 + return $self->{dsrs};
1.317 +}
1.318 +
1.319 +# Add a Feature 'Default Support Range' object.
1.320 +sub AddFeatureDSR
1.321 +{
1.322 + my $self = shift;
1.323 + return undef unless(ref($self));
1.324 + my $arg = shift;
1.325 + die "Method 'AddFeatureDSR' requires a 'FeatureDSR' object as argument.\n"
1.326 + unless(ref($arg) eq "FeatureDSR");
1.327 + push @{$self->FeatureDSRs()}, $arg;
1.328 + $self->NumDefUid($self->NumDefUid() + 1);
1.329 + return 1;
1.330 +}
1.331 +
1.332 +# This method loads up it's information from an existing feature manager
1.333 +# data file. This will die if it thinks there is something wrong with the file.
1.334 +sub LoadUp
1.335 +{
1.336 + my $self = shift;
1.337 + return undef unless(ref($self) eq "FMCreate");
1.338 +
1.339 + my $packprefix16 = lc($self->{packprefix});
1.340 + my $packprefix32 = uc($self->{packprefix});
1.341 +
1.342 + my $file = shift;
1.343 + return undef unless(defined($file) and -f $file);
1.344 + open FILE, $file or die "Couldn't open '$file'\n";
1.345 + binmode FILE;
1.346 + my ($tmp, $feat);
1.347 +
1.348 + # First get the file size.
1.349 + my $fsz = sysseek(FILE, 0, 2);
1.350 + sysseek(FILE, 0, 0);
1.351 +
1.352 + # Read the 'feat' marker from the top of the file. Check it.
1.353 + die "Unable to read first 4 bytes from '$file'"
1.354 + unless(4 == sysread(FILE, $feat, 4) );
1.355 + die "First four bytes of '$file' do not contain 'feat'"
1.356 + unless($feat eq "feat");
1.357 + $self->TypeField($feat); # Pointless. It's set to that anyway.
1.358 +
1.359 + # Read the file version number.
1.360 + die "Unable to read two bytes from index 4 from '$file'"
1.361 + unless(2 == sysread(FILE, $tmp, 2) );
1.362 + my $filever = unpack( $packprefix16, $tmp );
1.363 + $self->FileVersion($filever);
1.364 +
1.365 + # Read the file flags.
1.366 + die "Unable to read two bytes from index 6 from '$file'"
1.367 + unless(2 == sysread(FILE, $tmp, 2) );
1.368 + my $fileflags = unpack( $packprefix16, $tmp );
1.369 + $self->FileFlags($fileflags);
1.370 +
1.371 + # Read the number of features. Don't do anything with this yet..
1.372 + die "Unable to read four bytes from index 8 from '$file'"
1.373 + unless(4 == sysread(FILE, $tmp, 4) );
1.374 + my $nfeat = unpack( $packprefix32, $tmp );
1.375 +
1.376 + # Read the number of DSRs. Don't do anything with this yet..
1.377 + die "Unable to read four bytes from index 12 from '$file'"
1.378 + unless(4 == sysread(FILE, $tmp, 4) );
1.379 + my $ndsr = unpack( $packprefix32, $tmp );
1.380 +
1.381 + # Forget it if the filesize is clearly wrong.
1.382 + my $expsz = 16 + 12*$nfeat + 8*$ndsr;
1.383 + die "The file '$file' is $fsz bytes long, but the content suggests it should be $expsz bytes long. NFeatures: $nfeat NDSRs: $ndsr\n" unless($expsz == $fsz);
1.384 +
1.385 + # Now read in the feature flags.
1.386 + my $offset = 16;
1.387 + for(my $ff=0 ; $ff<$nfeat ; $ff++)
1.388 + {
1.389 + # Get the UID.
1.390 + die "Unable to read four bytes (uid) from index $offset from '$file'"
1.391 + unless(4 == sysread(FILE, $tmp, 4) );
1.392 + $offset += 4;
1.393 + my $uid = unpack( $packprefix32, $tmp );
1.394 +
1.395 + # Get the status word.
1.396 + die "Unable to read four bytes (sw) from index $offset from '$file'"
1.397 + unless(4 == sysread(FILE, $tmp, 4) );
1.398 + $offset += 4;
1.399 + my $sw = unpack( $packprefix32, $tmp );
1.400 +
1.401 + # Get the user data word.
1.402 + die "Unable to read four bytes (udw) from index $offset from '$file'"
1.403 + unless(4 == sysread(FILE, $tmp, 4) );
1.404 + $offset += 4;
1.405 + my $ud = unpack( $packprefix32, $tmp );
1.406 +
1.407 + my $featflag = FeatureFlag->new($uid, $sw, $ud);
1.408 + die "Couldn't create a feature flag object!\n" unless(ref($featflag));
1.409 + $self->AddFeatureFlag($featflag);
1.410 + }
1.411 +
1.412 + # Now read in the DSRs.
1.413 + for( my $dsr=0 ; $dsr<$ndsr ; $dsr++ )
1.414 + {
1.415 + # Get the low UID.
1.416 + die "Unable to read four bytes (lowuid) from index $offset from '$file'"
1.417 + unless(4 == sysread(FILE, $tmp, 4) );
1.418 + $offset += 4;
1.419 + my $lowuid = unpack( $packprefix32, $tmp );
1.420 +
1.421 + # Get the high UID.
1.422 + die "Can't read four bytes (high uid) from index $offset from '$file'"
1.423 + unless(4 == sysread(FILE, $tmp, 4) );
1.424 + $offset += 4;
1.425 + my $highuid = unpack( $packprefix32, $tmp );
1.426 +
1.427 + my $fd = FeatureDSR->new($lowuid, $highuid);
1.428 + die "Couldn't create 'FeatureDSR' object!\n" unless(ref($fd));
1.429 + $self->AddFeatureDSR($fd);
1.430 + }
1.431 +
1.432 + # Check if our calculated file offset matches the end of the file.
1.433 + # This is pointless actually, because we've already checked the file
1.434 + # size..
1.435 + my $fileoffset = sysseek(FILE, 0, 2);
1.436 + die "End of file offset ($fileoffset) does not match end of DSRs!\n"
1.437 + unless($fileoffset == $offset);
1.438 +
1.439 + close FILE;
1.440 + return 1;
1.441 +}
1.442 +
1.443 +# Remove the feature flag object specified by UID held in this object (in
1.444 +# the internal 'featureflags' array). Returns 1 on success, undef otherwise.
1.445 +sub RemoveFeatureFlagByUID
1.446 +{
1.447 + my $self = shift;
1.448 + return undef unless(ref($self));
1.449 + my $arg = shift;
1.450 + return undef unless(defined($arg));
1.451 + my $ffs = $self->FeatureFlags;
1.452 +
1.453 + my $idx = 0;
1.454 + for my $ff (@$ffs)
1.455 + {
1.456 + if($ff->UID() == $arg)
1.457 + {
1.458 + splice(@$ffs, $idx, 1);
1.459 + $self->NumFeatures($self->NumFeatures() - 1);
1.460 + return 1;
1.461 + }
1.462 + $idx++;
1.463 + }
1.464 + return undef;
1.465 +}
1.466 +
1.467 +# Return a reference to the 'FeatureFlag' object held in this object (in
1.468 +# the internal 'featureflags' array) with the uid specified as an
1.469 +# argument. This returns a reference so it's still in this object on return,
1.470 +# you can modify it and then write out (for example) the data file.
1.471 +sub GetFeatureFlagByUID
1.472 +{
1.473 + my $self = shift;
1.474 + return undef unless(ref($self));
1.475 + my $arg = shift;
1.476 + return undef unless(defined($arg));
1.477 + my $ffs = $self->FeatureFlags;
1.478 + for my $ff (@$ffs)
1.479 + {
1.480 + return $ff if($ff->UID() == $arg);
1.481 + }
1.482 + return undef;
1.483 +}
1.484 +
1.485 +
1.486 +# Remove the feature DSR object specified by UIDs held in this object (in
1.487 +# the internal 'dsrs' array). Returns 1 on success, undef otherwise.
1.488 +sub RemoveDSRByUIDs
1.489 +{
1.490 + my $self = shift;
1.491 + return undef unless(ref($self));
1.492 + my($lowuid, $highuid) = @_;
1.493 + return undef unless(defined($lowuid) and defined($highuid));
1.494 + my $fdsrs = $self->FeatureDSRs;
1.495 +
1.496 + my $idx = 0;
1.497 + for my $fdsr (@$fdsrs)
1.498 + {
1.499 + if( ($fdsrs->LowUID() == $lowuid) and
1.500 + ($fdsrs->HighUID() == $highuid) )
1.501 + {
1.502 + splice(@$fdsrs, $idx, 1);
1.503 + $self->NumDefUid($self->NumDefUid() - 1);
1.504 + return 1;
1.505 + }
1.506 + $idx++;
1.507 + }
1.508 + return undef;
1.509 +}
1.510 +
1.511 +# Return a reference to the 'FeatureDSR' object held in this object (in
1.512 +# the internal 'dsrs' array) with the low and high uids specified in the
1.513 +# arguments. This returns a reference so it's still in this object on return,
1.514 +# you can modify it (by changing the uids) and then write out (for example)
1.515 +# the data file.
1.516 +sub GetDSRByUIDs
1.517 +{
1.518 + my $self = shift;
1.519 + return undef unless(ref($self));
1.520 + my($lowuid, $highuid) = @_;
1.521 + return undef unless(defined($lowuid) and defined($highuid));
1.522 + my $fdsrs = $self->FeatureDSRs;
1.523 + for my $fdsr (@$fdsrs)
1.524 + {
1.525 + return $fdsr if( ($fdsr->LowUID() == $lowuid) and
1.526 + ($fdsr->HighUID() == $highuid));
1.527 + }
1.528 + return undef;
1.529 +}
1.530 +
1.531 +1;
1.532 +