suitestore_common.h

来自「This is a resource based on j2me embedde」· C头文件 代码 · 共 564 行 · 第 1/2 页

/*
 *
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program 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 version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

/**
 * @file
 *
 * This header file is interface to the common MIDlet suite storage
 * functions.
 */

#ifndef _SUITESTORE_COMMON_H_
#define _SUITESTORE_COMMON_H_

#include <kni.h>
#include <pcsl_string.h>
#include <midp_global_status.h>
#include <midpStorage.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Type of the midlet suite ID.
 */
typedef jint SuiteIdType;

/**
 * Type of the midlet suite's component ID.
 */
typedef jint ComponentIdType;

/**
 * Type of the AMS folder ID.
 */
typedef jint FolderIdType;

/**
 * Predefined suite IDs.
 */
#define UNUSED_SUITE_ID     0
#define INTERNAL_SUITE_ID  -1
#define MAX_SUITE_ID        2147483647

/** ID that is never used for a dynamic component of a midlet suite */
#define UNUSED_COMPONENT_ID 0
#define MAX_COMPONENT_ID    2147483647

/**
 * Length of string representation of the suite ID.
 * For example, "0000000F" for suiteId = 15.
 */
#define GET_SUITE_ID_LEN(suiteId) 8

/**
 * Length of string representation of the suite ID.
 */
#define GET_COMPONENT_ID_LEN(componentId) 8

/** A list of properties that can be searched by a key. */
typedef struct _Properties {
    /**
     * Number of properties, there are 2 Strings (key/value)
     * for each property
     */
    int numberOfProperties;
    /**
     * Creation status:
     *        0 success,
     *        OUT_OF_MEM_LEN if out of memory,
     *        IO_ERROR_LEN if an IO error occurred
     */
    int status;
    pcsl_string* pStringArr;
} MidpProperties;

/** Possible types of an installed component. */
typedef enum _ComponentType {
    COMPONENT_REGULAR_SUITE,
    COMPONENT_PREINSTALLED_SUITE,
    COMPONENT_DYNAMIC,
    /** force enum to be 4 bytes */
    COMPONENT_DUMMY = 0x10000000
} ComponentType;

/*
 * Maximal lenght of the hash. Currently MD5 is used so this value is set to 16.
 */
#define MAX_HASH_SIZE 16

/*
 * NOTE: maximal path length must not exceed the corresponding number
 * (now it is set to 128 2-byte characters) in the following macro.
 * 7 is the number of pcsl_strings in _variableLenSuiteData structure.
 */
#define MAX_VAR_SUITE_DATA_LEN ((128 * 2 + sizeof(jint)) * 7 + MAX_HASH_SIZE)

/**
 * A structure containing variable-length information (such as
 * a suite name and vendor name)about the installed midlet suites.
 */
typedef struct _variableLenSuiteData {
    /** Hash value (currently MD5) of the suite's jar file. */
    unsigned char* pJarHash;

    /**
     * jint (length) + UTF16 string
     * Class name of the midlet in single-midlet suite.
     * Not used (length field is 0) if the suite contains several midlets.
     */
    pcsl_string midletClassName;

    /**
     * jint (length) + UTF16 string
     * A name that will be displayed in the Application Manager.
     */
    pcsl_string displayName;

    /**
     * jint (length) + UTF16 string
     * Icon's name for this suite.
     */
    pcsl_string iconName;

    /**
     * jint (length) + UTF16 string
     * Vendor of the midlet suite.
     */
    pcsl_string suiteVendor;

    /**
     * jint (length) + UTF16 string
     * Name of the midlet suite.
     */
    pcsl_string suiteName;

    /**
     * jint (length) + UTF16 string
     * Full path to suite's jar file.
     */
    pcsl_string pathToJar;

    /**
     * jint (length) + UTF16 string
     * Full path to the settings files.
     */
    pcsl_string pathToSettings;
} VariableLenSuiteData;

/**
 * A structure containing all of the information about the installed
 * midlet suites required at the strartup time.
 * The first field in _suites.dat is "int suitesNum" - number of the
 * installed suites, then there is a list of MidletSuiteData structures.
 */
typedef struct _midletSuiteData {
    /**
     * Unique ID of the midlet suite
     * (0 means that this entry was removed).
     */
    SuiteIdType suiteId;

    /**
     * ID of the dynamic component (has meaning only if
     * the value of "type" field is COMPONENT_DYNAMIC).
     */
    ComponentIdType componentId;

    /**
     * ID of the storage (INTERNAL_STORAGE_ID for the internal storage
     * or another value for external storages).
     */
    jint storageId;

    /**
     * ID of the folder (see src/ams/ams_folders library for more info).
     */
    jint folderId;

    /** True if the suite enabled, false otherwise. */
    jboolean isEnabled;

    /** True if the suite is trusted, false otherwise. */
    jboolean isTrusted;

    /** True if the suite is temporary, false otherwise. */
    jboolean isTemporary;

    /** Number of midlets in this suite. */
    jint numberOfMidlets;

    /** Installation time (timestamp). */
    long installTime;

    /** Size of the midlet suite's jad file. */
    jint jadSize;

    /** Size of the midlet suite's jar file. */
    jint jarSize;

    /** Total size of all files except RMS belonging to the suite. */
    jint suiteSize;

    /** Size of the jar file hash. If it is 0, pJarHash field is empty. */
    jint jarHashLen;

    /**
     * Type of the component described by this structure.
     * If it is COMPONENT_PREINSTALLED_SUITE, this is a preinstalled
     * midlet suite and thus it should be prevented from being removed.
     */
    ComponentType type;

    /** A structure with string-represented information about the suite. */
    VariableLenSuiteData varSuiteData;

    /** True if it was checked that this suite is not corrupted. */
    jboolean isChecked;

    /** Application ID assigned by the external application manager. */
    jint externalAppId;

    /** Pointer to the next entry in the linked list. */
    struct _midletSuiteData* nextEntry;
} MidletSuiteData;

#define MIDLET_SUITE_DATA_SIZE (sizeof(MidletSuiteData) - \
    sizeof(VariableLenSuiteData) - sizeof(jboolean) - \
        sizeof(jint) - sizeof(MidletSuiteData*))

/**
 * Initializes the SuiteStore subsystem.
 */
MIDPError midp_suite_storage_init();

/**
 * Finalizes the SuiteStore subsystem.
 */
void midp_suite_storage_cleanup();

/**
 * Converts the given SuiteID to pcsl_string.
 * NOTE: this function returns a pointer to the static buffer!
 *
 * @param value suite id to convert
 * @return pcsl_string representation of the given suite id
 */
const pcsl_string* midp_suiteid2pcsl_string(SuiteIdType value);

/**
 * Converts the given suite ID to array of chars.
 * NOTE: this function returns a pointer to the static buffer!
 *
 * @param value suite id to convert
 *
 * @return char[] representation of the given suite ID
 * or NULL in case of error
 */
const char* midp_suiteid2chars(SuiteIdType value);