#!/usr/bin/env python

# -*- coding: utf-8 -*-

##############################################################################

# sisfield.py - Symbian OS v9.x SIS file utilities, SISField support classes

# Copyright 2006, 2007 Jussi Ylänen

#

# This file is part of Ensymble developer utilities for Symbian OS(TM).

#

# Ensymble is free software; you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation; either version 2 of the License, or

# (at your option) any later version.

#

# Ensymble is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with Ensymble; if not, write to the Free Software

# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

##############################################################################

import struct

import zlib

import symbianutil

# TODO: 1. Make all tostring() methods cache the result.

# TODO: 2. Allow modifying objects after creation, keeping string cache in sync.

# TODO: 3. Implement a list-of-strings type, which the tostring() (or

#          some other method with a better name) can use, to eliminate

#          superfluous string concatenations.

##############################################################################

# Parameters

##############################################################################

DEBUG               = 0     # (0: None, 1: Basic, 2: Verbose)

MAXNUMSIGNATURES    = 8     # Maximum number of signatures in a SISController

##############################################################################

# Public SISField constants (in original Symbian OS naming style)

##############################################################################

ECompressAuto                   = -1    # Not a real compression type

ECompressNone                   = 0

ECompressDeflate                = 1

EInstInstallation               = 0

EInstAugmentation               = 1

EInstPartialUpgrade             = 2

EInstPreInstalledApp            = 3

EInstPreInstalledPatch          = 4

EInstFlagShutdownApps           = 1

EOpInstall                      = 1

EOpRun                          = 2

EOpText                         = 4

EOpNull                         = 8

EInstVerifyOnRestore            = 1 << 15

EInstFileRunOptionInstall       = 1 << 1

EInstFileRunOptionUninstall     = 1 << 2

EInstFileRunOptionByMimeType    = 1 << 3

EInstFileRunOptionWaitEnd       = 1 << 4

EInstFileRunOptionSendEnd       = 1 << 5

EInstFileTextOptionContinue     = 1 << 9    # Not used by makesis v. 4, 0, 0, 2

EInstFileTextOptionSkipIfNo     = 1 << 10

EInstFileTextOptionAbortIfNo    = 1 << 11

EInstFileTextOptionExitIfNo     = 1 << 12

ESISHashAlgSHA1                 = 1

ESISSignatureAlgSHA1RSA         = "1.2.840.113549.1.1.5"

ESISSignatureAlgSHA1DSA         = "1.2.840.10040.4.3"

EBinOpEqual                     = 1

EBinOpNotEqual                  = 2

EBinOpGreaterThan               = 3

EBinOpLessThan                  = 4

EBinOpGreaterOrEqual            = 5

EBinOpLessOrEqual               = 6

ELogOpAnd                       = 7

ELogOpOr                        = 8

EUnaryOpNot                     = 9

EFuncExists                     = 10

EFuncAppProperties              = 11

EFuncDevProperties              = 12

EPrimTypeString                 = 13

EPrimTypeOption                 = 14

EPrimTypeVariable               = 15

EPrimTypeNumber                 = 16

EVarLanguage                    = 0x1000

EVarRemoteInstall               = 0x1001

##############################################################################

# Public exception class for SIS parsing / generation

##############################################################################

class SISException(StandardError):

    '''SIS parsing / generation error'''

    pass

##############################################################################

# Public module-level functions

##############################################################################

def SISField(fromstring, exactlength = True):

    '''Generator function for creating SISField subclass instances from a string

    If exactlength is False, return a tuple of (SISField, bytes consumed).

    Otherwise return SISField directly.'''

    # Determine SISField subclass type.

    ftype, hdrlen, flen, padlen = parsesisfieldheader(fromstring, None,

                                                      exactlength)

    try:

        fclass = fieldnumtoclass[ftype]

    except KeyError:

        raise SISException("invalid SISField type '%d'" % ftype)

    # Limit string to actual data length (in case exactlength was False).

    fromstring = fromstring[:(hdrlen + flen + padlen)]

    # Create a subclass instance.

    field = fclass(fromstring = fromstring)

    if exactlength:

        return field

    else:

        # Normal SISField subclasses use SISField() to parse adjacent SISFields.

        # Number of consumed bytes need to be passed back in that case. This

        # may violate the idea of a generator function somewhat, but eliminates

        # a bit of duplicated code.

        return (field, len(fromstring))

def stripheaderandpadding(fromstring):

    '''Return the actual content of SISField string.

    stripheaderandpadding(...) -> contents

    fromstring  a SISField string

    contents    SISField contents without the header and padding'''

    # Parse field header.

    ftype, hdrlen, flen, padlen = parsesisfieldheader(fromstring)

    # Return field contents.

    return fromstring[hdrlen:(hdrlen + flen)]

##############################################################################

# Module-level functions which are normally only used by this module

##############################################################################

def parsesisfieldheader(string, requiredtype = None, exactlength = True):

    '''Parse the header of a SISField string and return the field type and

    lengths of the various parts (header, data, padding). Optionally, check

    that the type is correct and that the string length is not too long.'''

    hdrlen = 8

    if hdrlen > len(string):

        raise SISException("not enough data for a complete SISField header")

    # Get SISField type and first part of the length.

    ftype, flen = struct.unpack("<LL", string[:8])

    # Get rest of the SISField length, 31-bit or 63-bit.

    flen2 = None

    if flen & 0x8000000L:

        # 63-bit length, read rest of length.

        hdrlen = 12

        if hdrlen > len(string):

            raise SISException("not enough data for a complete SISField header")

        flen2 = struct.unpack("<L", string[8:12])[0]

        flen = (flen & 0x7ffffffL) | (flen2 << 31)

    # Calculate padding to 32-bit boundary.

    padlen = ((flen + 3) & ~0x3L) - flen

    if requiredtype != None and ftype != requiredtype:

        raise SISException("invalid SISField type '%d'" % ftype)

    if (hdrlen + flen + padlen) > len(string):

        raise SISException("SISField contents too short")

    # Allow oversized strings when parsing recursive SISFields.

    if exactlength and (hdrlen + flen + padlen) < len(string):

        raise SISException("SISField contents too long")

    return ftype, hdrlen, flen, padlen

def makesisfieldheader(fieldtype, fieldlen):

    '''Create a SISField header string from type and length.'''

    if fieldlen < 0x80000000L:

        # 31-bit length

        return struct.pack("<LL", fieldtype, fieldlen)

    else:

        # 63-bit length

        fieldlen2 = fieldlen >> 31

        fieldlen  = (fieldlen & 0x7fffffffL) | 0x80000000L

        return struct.pack("<LLL", fieldtype, fieldlen, fieldlen2)

def makesisfieldpadding(fieldlen):

    '''Create a string of zero bytes for padding to 32-bit boundary.

    Parameter may be either the whole field length (header + data)

    or just the data length.'''

    # Calculate padding to 32-bit boundary.

    padlen = ((fieldlen + 3) & ~0x3L) - fieldlen

    return "\x00" * padlen

##############################################################################

# SISField base classes

##############################################################################

class SISFieldBase(object):

    '''SISField base class'''

    def __init__(self, **kwds):

        if DEBUG > 0:

            # DEBUG: Print class name during initialization.

            print "%s.__init__()" % self.__class__.__name__

        # Get the names of all instance variables.

        validkwds = self.__dict__.keys()

        # Filter out private instance variables (all in lowercase).

        validkwds = filter(lambda s: s != s.lower(), validkwds)

        # Set type code.

        self.fieldtype = fieldnametonum[self.__class__.__name__]

        if "fromstring" in kwds:

            if DEBUG > 1:

                # DEBUG: Dump of string parameter.

                print repr(kwds["fromstring"])

            # Load instance variables from string.

            if len(kwds) != 1:

                raise TypeError(

                    "keyword 'fromstring' may not be given with other keywords")

            self.fromstring(kwds["fromstring"])

        else:

            # Load instance variables from keywords.

            # Only accept existing variable names.

            for kwd in kwds.keys():

                if kwd not in validkwds:

                    raise AttributeError("'%s' object has no attribute '%s'" %

                                         (self.__class__.__name__, kwd))

                self.__dict__[kwd] = kwds[kwd]

    def __str__(self):

        # Default __str__() for SISFields, only return the field name.

        return "<%s>" % self.__class__.__name__

class SISFieldNormal(SISFieldBase):

    '''SISField base class for normal fields (fields containing only other

    fields and integers)'''

    # Subfield types

    FTYPE_INTEGRAL  = 0     # Integer

    FTYPE_MANDATORY = 1     # Mandatory SISField

    FTYPE_OPTIONAL  = 2     # Optional SISField

    FTYPE_ARRAY     = 3     # SISArray with zero or more items

    def __init__(self, **kwds):

        # Initialize instance variables to None.

        for fattr, fkind, ffmt in self.subfields:

            self.__dict__[fattr] = None

        # Set instance variables.

        SISFieldBase.__init__(self, **kwds)

        for fattr, fkind, ffmt in self.subfields:

            # Check that all required instance variables are set.

            if fkind != self.FTYPE_OPTIONAL and self.__dict__[fattr] == None:

                raise AttributeError("missing '%s' attribute for '%s'" %

                                     (fattr, self.__class__.__name__))

            if fkind in (self.FTYPE_MANDATORY, self.FTYPE_OPTIONAL):

                # Verify SISField types.

                if (self.__dict__[fattr] != None and

                    fieldnumtoname[self.__dict__[fattr].fieldtype] != ffmt):

                    raise TypeError(

                        "attribute '%s' for '%s' is of invalid SISField type" %

                        (fattr, self.__class__.__name__))

            elif fkind == self.FTYPE_ARRAY:

                # Verify SISArray contents.

                if (fieldnumtoname[self.__dict__[fattr].fieldtype] != "SISArray"

                    or

                    fieldnumtoname[self.__dict__[fattr].SISFieldType] != ffmt):

                    raise TypeError(

                        "SISArray attribute '%s' for '%s' is of invalid type" %

                        (fattr, self.__class__.__name__))

    def fromstring(self, string):

        # Parse field header.

        ftype, hdrlen, flen, padlen = parsesisfieldheader(string,

                                                          self.fieldtype)

        # Recursively parse subfields.

        pos = hdrlen

        reuse = None    # SISField to re-use or None

        try:

            for fattr, fkind, ffmt in self.subfields:

                field = None    # No value by default

                if fkind == self.FTYPE_INTEGRAL:

                    # Integer, unpack it.

                    if reuse:

                        # It is an error if there is a field to

                        # re-use present at this time.

                        raise ValueError("integral field preceded optional")

                    n = struct.calcsize(ffmt)

                    field = struct.unpack(ffmt, string[pos:(pos + n)])[0]

                    pos += n

                else:

                    # SISField, read data from string or

                    # re-use field from previous round.

                    if not reuse:

                        # No old field to handle, convert string to SISField.

                        if pos < (hdrlen + flen):

                            field, n = SISField(string[pos:(hdrlen + flen)],

                                                False)

                            pos += n

                        elif fkind != self.FTYPE_OPTIONAL:

                            # No more data in string, raise an exception.

                            raise ValueError("unexpected end-of-data")

                    else:

                        # Field from previous round present, re-use it.

                        field = reuse

                        reuse = None

                    # Verify SISField type.

                    if field != None:

                        fname = fieldnumtoname[field.fieldtype]

                        if fkind == self.FTYPE_ARRAY:

                            if (fname != "SISArray" or

                                fieldnumtoname[field.SISFieldType] != ffmt):

                                    # Wrong type of fields inside SISArray,

                                    # raise an exception.

                                    raise ValueError("invalid SISArray type")

                        elif fkind == self.FTYPE_MANDATORY:

                            if fname != ffmt:

                                # Mandatory field missing, raise an exception.

                                raise ValueError("mandatory field missing")

                        elif fkind == self.FTYPE_OPTIONAL:

                            if fname != ffmt:

                                # Wrong type for optional field. Skip optional

                                # field and re-use already parsed field on next

                                # round.

                                reuse = field

                                field = None

                # Introduce field as an instance variable.

                self.__dict__[fattr] = field

        except (ValueError, KeyError, struct.error):

            if DEBUG > 0:

                # DEBUG: Raise a detailed exception.

                raise

            else:

                raise SISException("invalid '%s' structure" %

                                   self.__class__.__name__)

    def tostring(self):

        # Recursively create strings from subfields.

        fstrings = [None]

        totlen = 0

        for fattr, fkind, ffmt in self.subfields:

            field = self.__dict__[fattr]

            if fkind == self.FTYPE_INTEGRAL:

                # Integer, pack it.

                try:

                    string = struct.pack(ffmt, field)

                except:

                    print "%s %s %s" % (self.__class__, ffmt, repr(field))

                    raise

                fstrings.append(string)

                totlen += len(string)

            else:

                if field == None:

                    if fkind == self.FTYPE_OPTIONAL:

                        # Optional field missing, skip it.

                        pass

                    else:

                        # Mandatory field missing, raise an exception.

                        raise SISException("field '%s' missing for '%s'" %

                                           (fattr, self.__dict__.__name__))

                else:

                    # Convert SISField to string.

                    string = field.tostring()

                    fstrings.append(string)

                    totlen += len(string)

        try:

            del string  # Try to free some memory early.

        except:

            pass

        fstrings[0] = makesisfieldheader(self.fieldtype, totlen)

        fstrings.append(makesisfieldpadding(totlen))

        # TODO: Heavy on memory, optimize (new string type with concat.)

        return "".join(fstrings)

class SISFieldSpecial(SISFieldBase):

    '''SISField base class for special fields (fields that do something

    special for the data they contain or the data is of variable length)'''

    def __init__(self, **kwds):

        # Set instance variables.

        SISFieldBase.__init__(self, **kwds)

##############################################################################

# Special SISField subclasses

##############################################################################

class SISString(SISFieldSpecial):

    '''UCS-2 (UTF-16LE) string'''

    def __init__(self, **kwds):

        # Set default values.

        self.String = None

        # Parse keyword parameters.

        SISFieldSpecial.__init__(self, **kwds)

        # Check that all required instance variables are set.

        if self.String == None:

            raise AttributeError("missing '%s' attribute for '%s'" %

                                 ("String", self.__class__.__name__))

    def fromstring(self, string):

        ftype, hdrlen, flen, padlen = parsesisfieldheader(string,

                                                          self.fieldtype)

        self.String = string[hdrlen:(hdrlen + flen)].decode("UTF-16LE")

    def tostring(self):

        encstr = self.String.encode("UTF-16LE")

        return "%s%s%s" % (makesisfieldheader(self.fieldtype, len(encstr)),

                           encstr, makesisfieldpadding(len(encstr)))

    def __str__(self):

        # Always return Unicode string. Let Python default encoding handle it.

        return u"<SISString '%s'>" % self.String

class SISArray(SISFieldSpecial):

    '''An array of other SISFields, all of the same type'''

    def __init__(self, **kwds):

        # Set default values.

        self.SISFieldType = None    # Invalid type, checked later.

        self.SISFields = []

        # Parse keyword parameters.

        SISFieldSpecial.__init__(self, **kwds)

        # Make a copy of the supplied list

        # (caller may try to modify the original).

        self.SISFields = self.SISFields[:]

        # Allow type to be a string or number.

        self.SISFieldType = fieldnametonum.get(self.SISFieldType,

                                               self.SISFieldType)

        # Get type of first field if not given explicitly.

        if self.SISFieldType == None:

            if len(self.SISFields) > 0:

                self.SISFieldType = self.SISFields[0].fieldtype

            else:

                raise AttributeError("no SISFieldType given")

        # Check that all fields are of the same type.

        for f in self.SISFields:

            if f.fieldtype != self.SISFieldType:

                raise TypeError("SISFieldType mismatch for SISArray")

    def fromstring(self, string):

        # Parse field header.

        ftype, hdrlen, flen, padlen = parsesisfieldheader(string,

                                                          self.fieldtype)

        if flen < 4:

            raise SISException("not enough data for a complete SISArray header")

        # Get array type (type of SISFields in the array).

        atype = struct.unpack("<L", string[hdrlen:(hdrlen + 4)])[0]

        pos = hdrlen + 4    # Skip SISFieldType.

        totlen = hdrlen + flen

        fields = []

        while pos < totlen:

            # Get first part of the SISField length.

            alen = struct.unpack("<L", string[pos:(pos+4)])[0]

            pos += 4

            # Get rest of the SISField length, 31-bit or 63-bit.

            alen2 = None

            if alen & 0x8000000L:

                # 63-bit length, read rest of length.

                alen2 = struct.unpack("<L", string[pos:(pos+4)])[0]

                alen = (alen & 0x7ffffffL) | (alen2 << 31)

                pos += 4

            # Calculate padding to 32-bit boundary.

            apadlen = ((alen + 3) & ~0x3L) - alen

            # Construct a valid SISField header and proper padding.

            fhdr = makesisfieldheader(atype, alen)

            fpad = makesisfieldpadding(alen)

            # Create a SISField.

            # TODO: Heavy on memory, optimize (new string type with concat.)

            field = SISField(fhdr + string[pos:(pos + alen)] + fpad)