#!/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")