ensymble 0.29-1 / usr / share / pyshared / ensymble / utils / symbianutil.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-

##############################################################################
# symbianutil.py - Utilities for working with Symbian OS-related data
# Copyright 2006, 2007, 2008, 2009 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


##############################################################################
# Miscellaneous functions
##############################################################################

def uidstostring(uid1, uid2, uid3):
    '''Return a string of UIDs and a checksum.'''

    crc = uidcrc(uid1, uid2, uid3)
    return struct.pack("<LLLL", uid1, uid2, uid3, crc)

def ise32image(string):
    '''Check if a given string contains a valid E32Image header.
    Return "EXE", "DLL" or None.'''

    if len(string) < 156:
        # Minimum header size is 156 bytes.
        return None

    if string[16:20] != "EPOC":
        # Wrong cookie, not an E32Image header.
        return None

    # Get UIDs as integers.
    uid1, uid2, uid3 = struct.unpack("<LLL", string[:12])

    # Verify UID checksum.
    uidstr = uidstostring(uid1, uid2, uid3)
    if uidstr != string[:16]:
        # Invalid UID checksum.
        return None

    # Check type of E32Image header.
    if uid1 == 0x10000079L:
        return "DLL"
    elif uid1 == 0x1000007AL:
        return "EXE"

    # Not an EXE or DLL.
    return None

def e32imageinfo(image):
    '''Return a tuple with the UID1, UID2, UID3, secure ID, vendor ID and
    capabilities (as a string) of the given e32image.'''

    if ise32image(image) == None:
        raise ValueError("not a valid e32image header")

    uid1, uid2, uid3 = struct.unpack("<LLL", image[:12])
    secureid = struct.unpack("<L", image[128:132])[0]
    vendorid = struct.unpack("<L", image[132:136])[0]
    capabilities = struct.unpack("<Q", image[136:144])[0]

    return (uid1, uid2, uid3, secureid, vendorid, capabilities)

def parseintmagnitude(string):
    '''Parse an integer and a magnitude. Magnitude can be "k" or "M" (case
    is not important). There may be no white-space between the integer and
    magnitude. Magnitudes are interpreted as 1024 and 1048576.'''

    string = string.lower()

    if string[-1] == "k":
        magnitude = 1024
        string = string[:-1]
    elif string[-1] == "m":
        magnitude = 1024 * 1024
        string = string[:-1]
    else:
        magnitude = 1

    return int(string, 10) * magnitude

def uidfromname(basename):
    '''Generate a test-range UID (0xe0000000 to 0xefffffff) from a
    Unicode name.'''

    # Normalise case.
    basename = basename.lower()

    # Convert Unicode name to an unambiguous byte string.
    basename = basename.encode("utf8")

    # Calculate a 32-bit CCITT CRC and set top four bits to "e".
    return (crc32ccitt(basename) & 0x0fffffffL) | 0xe0000000L

def e32imagecaps(string):
    '''Check if a given string is an E32Image file and return its
    capabilities or None if not an E32Image.

    Returned value can be directly used as the "capabilities"
    attribute of sisfile.SimpleSISWriter().addfile() call.'''

    if ise32image(string) == None:
        return None

    return struct.unpack("<Q", string[136:144])[0]


##############################################################################
# Checksum functions for various types of checksums in Symbian OS
##############################################################################

def crc16ccitt(string, initialvalue = 0x0000, finalxor = 0x0000):
    '''Calculate a CCITT CRC-16 checksum using a
    slow and straightforward algorithm.'''

    value = initialvalue
    for c in string:
        value ^= (ord(c) << 8)
        for b in xrange(8):
            value <<= 1
            if value & 0x10000:
                value ^= 0x1021
            value &= 0xffff

    return value ^ finalxor

def crc32ccitt(data, initialvalue = 0x00000000L, finalxor = 0x00000000L):
    '''Use zlib to calculate a CCITT CRC-32 checksum. Work around zlib
    signedness problems.'''

    if initialvalue >= 0x80000000L:
        initialvalue -= 0x100000000L
    initialvalue = int(initialvalue)

    value = long(zlib.crc32(data, initialvalue))

    if value < 0:
        value += 0x100000000L

    return value ^ finalxor

def uidcrc(uid1, uid2, uid3):
    '''Calculate a Symbian OS UID checksum.'''

    # Convert UIDs to a string and group even and odd characters
    # into separate strings (in a Python v2.2 compatible way).
    uidstr = struct.pack("<LLL", uid1, uid2, uid3)
    evenchars = "".join([uidstr[n] for n in range(0, 12, 2)])
    oddchars  = "".join([uidstr[n] for n in range(1, 12, 2)])

    # Calculate 16-bit CCITT CRCs for even and odd characters.
    evencrc = crc16ccitt(evenchars)
    oddcrc  = crc16ccitt(oddchars)

    # Resulting 32-bit UID CRC is a combination of the two 16-bit CCITT CRCs.
    return (long(oddcrc) << 16) | evencrc

def e32imagecrc(image, uid3 = None, secureid = None, vendorid = None,
                heapsizemin = None, heapsizemax = None, capabilities = None):
    '''Return a modified e32image (or just the header) with UID checksum
    and header checksum (CCITT CRC-32) recalculated. Optionally modify
    the UID3, secure ID, vendor ID, heap size and capability bit mask.'''

    if ise32image(image) == None:
        raise ValueError("not a valid e32image header")

    # Get original UIDs as integers.
    uid1, uid2, uid3_orig = struct.unpack("<LLL", image[:12])

    # Get modified or original IDs depending on parameters. Convert to strings.
    if uid3 == None:
        uid3 = uid3_orig
    uid3str = struct.pack("<L", uid3)

    if secureid == None:
        secureidstr = image[128:132]
    else:
        secureidstr = struct.pack("<L", secureid)

    if vendorid == None:
        vendoridstr = image[132:136]
    else:
        vendoridstr = struct.pack("<L", vendorid)

    if heapsizemin == None:
        heapsizeminstr = image[56:60]
    else:
        heapsizeminstr = struct.pack("<l", heapsizemin)

    if heapsizemax == None:
        heapsizemaxstr = image[60:64]
    else:
        heapsizemaxstr = struct.pack("<l", heapsizemax)

    if capabilities == None:
        capabilitiesstr = image[136:144]
    else:
        capabilitiesstr = struct.pack("<Q", capabilities)

    # Re-calculate UID checksum.
    uidstr = uidstostring(uid1, uid2, uid3)

    # Use initial CRC of 0xc90fdaa2L (KImageCrcInitialiser in f32image.h).
    initialcrcstr = struct.pack("<L", 0xc90fdaa2L)

    # Construct a new header for CRC-32 calculation.
    newheader = "%s%s%s%s%s%s%s%s%s%s%s" % (uidstr, image[16:20], initialcrcstr,
                                            image[24:56], heapsizeminstr,
                                            heapsizemaxstr, image[64:128],
                                            secureidstr, vendoridstr,
                                            capabilitiesstr, image[144:156])

    crc32 = crc32ccitt(newheader, 0xffffffffL, 0xffffffffL)
    crc32str = struct.pack("<L", crc32)

    # Construct and return a new image (or header) with the correct checksum.
    return "%s%s%s%s" % (newheader[0:20], crc32str,
                         newheader[24:156], image[156:])


##############################################################################
# Symbian OS language mappings
##############################################################################

langinfo = [
    ("AF", "Afrikaans",             34),
    ("SQ", "Albanian",              35),
    ("AM", "AmericanEnglish",       10),
    ("AH", "Amharic",               36),
    ("AR", "Arabic",                37),
    ("HY", "Armenian",              38),
    ("AU", "Australian",            20),
    ("AS", "Austrian",              22),
    ("BE", "Belarussian",           40),
    ("BL", "BelgianFlemish",        19),
    ("BF", "BelgianFrench",         21),
    ("BN", "Bengali",               41),
    ("BP", "BrazilianPortuguese",   76),
    ("BG", "Bulgarian",             42),
    ("MY", "Burmese",               43),
    ("CE", "CanadianEnglish",       46),
    ("CF", "CanadianFrench",        51),
    ("CA", "Catalan",               44),
    ("HR", "Croatian",              45),
    ("CG", "CyprusGreek",           55),
    ("CT", "CyprusTurkish",         91),
    ("CS", "Czech",                 25),
    ("DA", "Danish",                7),
    ("DU", "Dutch",                 18),
    ("EN", "English",               1),
    ("ET", "Estonian",              49),
    ("FA", "Farsi",                 50),
    ("FS", "FinlandSwedish",        85),
    ("FI", "Finnish",               9),
    ("FR", "French",                2),
    ("KA", "Georgian",              53),
    ("GE", "German",                3),
    ("EL", "Greek",                 54),
    ("GU", "Gujarati",              56),
    ("HE", "Hebrew",                57),
    ("HI", "Hindi",                 58),
    ("HK", "HongKongChinese",       30),
    ("HU", "Hungarian",             17),
    ("IC", "Icelandic",             15),
    ("IN", "Indonesian",            59),
    ("IE", "InternationalEnglish",  47),
    ("IF", "InternationalFrench",   24),
    ("OS", "InternationalSpanish",  82),
    ("GA", "Irish",                 60),
    ("IT", "Italian",               5),
    ("JA", "Japanese",              32),
    ("KN", "Kannada",               62),
    ("KK", "Kazakh",                63),
    ("KM", "Khmer",                 64),
    ("KO", "Korean",                65),
    ("LO", "Laothian",              66),
    ("LS", "LatinAmericanSpanish",  83),
    ("LV", "Latvian",               67),
    ("LT", "Lithuanian",            68),
    ("MK", "Macedonian",            69),
    ("MS", "Malay",                 70),
    ("ML", "Malayalam",             71),
    ("MR", "Marathi",               72),
    ("MO", "Moldavian",             73),
    ("MN", "Mongolian",             74),
    ("NZ", "NewZealand",            23),
    ("NO", "Norwegian",             8),
    ("NN", "NorwegianNynorsk",      75),
    ("PL", "Polish",                27),
    ("PO", "Portuguese",            13),
    ("ZH", "PRCChinese",            31),
    ("PA", "Punjabi",               77),
    ("RO", "Romanian",              78),
    ("RU", "Russian",               16),
    ("GD", "ScotsGaelic",           52),
    ("SR", "Serbian",               79),
    ("SI", "Sinhalese",             80),
    ("SK", "Slovak",                26),
    ("SL", "Slovenian",             28),
    ("SO", "Somali",                81),
    ("SF", "SouthAfricanEnglish",   48),    # "SF" is also "SwissFrench"
    ("SP", "Spanish",               4),
    ("SH", "Swahili",               84),
    ("SW", "Swedish",               6),
    ("SF", "SwissFrench",           11),    # "SF" is also "SouthAfricanEnglish"
    ("SG", "SwissGerman",           12),
    ("SZ", "SwissItalian",          61),
    ("TL", "Tagalog",               39),
    ("TC", "TaiwanChinese",         29),
    ("TA", "Tamil",                 87),
    ("TE", "Telugu",                88),
    ("TH", "Thai",                  33),
    ("BO", "Tibetan",               89),
    ("TI", "Tigrinya",              90),
    ("TU", "Turkish",               14),
    ("TK", "Turkmen",               92),
    ("UK", "Ukrainian",             93),
    ("UR", "Urdu",                  94),
    ("VI", "Vietnamese",            96),
    ("CY", "Welsh",                 97),
    ("ZU", "Zulu",                  98)
]

langidtonum     = dict([(lid,   lnum)  for lid, lname, lnum in langinfo])
langnametonum   = dict([(lname, lnum)  for lid, lname, lnum in langinfo])
langnumtoname   = dict([(lnum,  lname) for lid, lname, lnum in langinfo])


##############################################################################
# Symbian OS capabilities
##############################################################################

capinfo = [
    ("TCB",             0),
    ("CommDD",          1),
    ("PowerMgmt",       2),
    ("MultimediaDD",    3),
    ("ReadDeviceData",  4),
    ("WriteDeviceData", 5),
    ("DRM",             6),
    ("TrustedUI",       7),
    ("ProtServ",        8),
    ("DiskAdmin",       9),
    ("NetworkControl",  10),
    ("AllFiles",        11),
    ("SwEvent",         12),
    ("NetworkServices", 13),
    ("LocalServices",   14),
    ("ReadUserData",    15),
    ("WriteUserData",   16),
    ("Location",        17),
    ("SurroundingsDD",  18),
    ("UserEnvironment", 19)
]

numcaps = 20
allcapsmask = (1L << numcaps) - 1

capnametonum = dict([(cname.lower(), cnum) for cname, cnum in capinfo])

def capstringtomask(string):
    '''Parse a capability string in which capability
    names are separated with + (include capability)
    and - (exclude capability).'''

    if string == "":
        # Empty string denotes no capabilities.
        return 0L

    try:
        # Allow numerical representation for capabilities.
        capmask = int(string, 0)
        if capmask < 0:
            raise ValueError
        return capmask
    except ValueError:
        # Capabilities not in numerical form, continue with parsing.
        pass

    # Erase an optional initial "+" character.
    if string[0] == '+':
        string = string[1:]

    # Split string before each "+" and "-" character.
    startpos = 0
    capnames = []
    for stoppos in xrange(len(string)):
        if string[stoppos] in ("+", "-"):
            capnames.append(string[startpos:stoppos])
            startpos = stoppos
    capnames.append(string[startpos:])  # The last one

    # Add initial "+" for the first name.
    capnames[0] = "+%s" % capnames[0]

    # Find a bit mask for each capability name.
    capmask = 0x00000000L
    for cname in capnames:
        # Convert capability name to lowercase for capnametonum[].
        cnamelower = cname.lower()

        if cnamelower[1:] == "all":
            mask = allcapsmask
        elif cnamelower[1:] == "none":
            mask = 0x00000000L
        else:
            try:
                mask = 1L << (capnametonum[cnamelower[1:]])
            except KeyError:
                raise ValueError("invalid capability name '%s'" % cname[1:])

        if cname[0] == '-':
            # Remove capability.
            capmask &= ~mask
        else:
            # Add capability.
            capmask |= mask

    return capmask

def capmasktostring(capmask, shortest = False):
    '''Generate (optionally) the shortest possible capability
    string using either capability names separated with + (include
    capability) or - (exclude capability).'''

    if capmask == 0L:
        # Special string for no capabilities.
        return "NONE"

    # Construct a list of set and unset capabilities.
    poscnames = []
    negcnames = ["ALL"]
    for cap in capinfo:
        mask = (1L << cap[1])
        if capmask & mask:
            poscnames.append(cap[0])
            capmask &= ~mask
        else:
            negcnames.append(cap[0])

    # Check that all capability bits are handled.
    if capmask != 0L:
        raise ValueError("invalid capability bits in mask: 0x%08x" % capmask)

    posstring = "+".join(poscnames)
    negstring = "-".join(negcnames)

    # Return the shortest string if requested, otherwise the "positive" string.
    if shortest and len(posstring) > len(negstring):
        return negstring
    return posstring

def capmasktorawdata(capmask):
    '''Convert capability bit mask to raw four- or eight-character string.'''

    if capmask < (1L << 32):
        return struct.pack("<L", int(capmask))
    elif capmask < (1L << 64):
        return struct.pack("<Q", capmask)
    else:
        raise ValueError("capability bit mask too long")

def rawdatatocapmask(rawdata):
    '''Convert raw four- or eight-character string to capability bit mask.'''

    if len(rawdata) == 4:
        return struct.unpack("<L", rawdata)[0]
    elif len(rawdata) == 8:
        return struct.unpack("<Q", rawdata)[0]
    else:
        raise ValueError("string length not a multiple of 32 bits")