suitestore_installer.h

来自「This is a resource based on j2me embedde」· C头文件 代码 · 共 210 行

/*
 *
 *
 * 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 contains Installer API of the MIDlet suite storage
 * subsystem. The functions declared in this header need not to be ported
 * if using a native installer (what is probably the case if using NAMS).
 */

#ifndef _SUITESTORE_INSTALLER_H_
#define _SUITESTORE_INSTALLER_H_

#include <pcsl_string.h>
#include <midp_global_status.h>
#include <suitestore_common.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * The information generated by install the suite installation process.
 */
typedef struct _MidpInstallInfo {
    /**
     * Creation status:
     *        ALL_OK success,
     *        OUT_OF_MEM_LEN if out of memory,
     *        IO_ERROR_LEN if an IO error occurred
     */
    MIDPError status;
    /** the absolute URL where the JAD came from, can be null. */
    pcsl_string jadUrl_s;
    /** the absolute URL where the JAR came from. */
    pcsl_string jarUrl_s;
    /** security domain of the suite */
    pcsl_string domain_s;
    /** true if suite is trusted, false if not */
    jboolean trusted;
    /**
     * if signed, the Certificate Authorization path, begining with the
     * most trusted entity, that authorized it
     */
    pcsl_string* authPath_as;
    /** length of the authorization path */
    jint authPathLen;
    /** suite hash for the suites with preverified classes */
    jbyte *pVerifyHash;
    /** suite hash length */
    int verifyHashLen;
    /**
     * suite properties given in the JAD as an array of strings in
     * key/value pair order, can be empty if jadUrl_s is null or empty
     */
    MidpProperties jadProps;
    /**
     * suite properties of the manifest as an array of strings
     * in key/value pair order
     */
    MidpProperties jarProps;
} MidpInstallInfo;

/**
 * Native representation of the SuiteSettings class.
 */
typedef struct _MidpSuiteSettings {
    /** Permissions for this suite. */
    jbyte* pPermissions;
    /** Number of permissions in pPermissions array. */
    jint permissionsLen;
    /** Can this MIDlet suite interrupt other suites. */
    jbyte pushInterruptSetting;
    /** Push options. */
    jint pushOptions;
    /** The ID of this suite. */
    SuiteIdType suiteId;
    /** If true, MIDlet from this suite can be run. */
    jboolean enabled;
} MidpSuiteSettings;

/**
 * Returns a unique identifier of MIDlet suite.
 *
 * @param pSuiteId [out] receives the platform-specific storage name of the
 *                       application
 *
 * @return ALL_OK if success, else an error code
 */
MIDPError
midp_create_suite_id(SuiteIdType* pSuiteId);

#if ENABLE_DYNAMIC_COMPONENTS
/**
 * Returns a unique identifier of a MIDlet suite's dynamic component.
 *
 * @param pComponentId [out] receives a platform-specific id of the component
 *
 * @return ALL_OK if success, else an error code
 */
MIDPError
midp_create_component_id(SuiteIdType* pComponentId);
#endif /* ENABLE_DYNAMIC_COMPONENTS */

/**
 * Gets the install information of a MIDlet suite.
 *
 * Note that memory for the strings inside the returned MidpInstallInfo
 * structure is allocated by the callee, and the caller is
 * responsible for freeing it using midp_free_install_info().
 *
 * @param suiteId ID of the suite
 *
 * @return Installation information, use status macros to check the result
 * A SUITE_CORRUPTED_ERROR is returned as a status in InstallInfo
 * when suite is corrupted
 */
MidpInstallInfo midp_get_suite_install_info(SuiteIdType suiteId);

/**
 * Frees an InstallInfo struct. Does nothing if passed NULL.
 *
 * @param pInstallInfo installation information returned from
 * midp_read_install_info().
 */
void midp_free_install_info(MidpInstallInfo* pInstallInfo);

/**
 * Stores or updates a midlet suite.
 *
 * @param pInstallInfo structure containing the following information:<br>
 * <pre>
 *     id - unique ID of the suite;
 *     jadUrl - where the JAD came from, can be null;
 *     jarUrl - where the JAR came from;
 *     jarFilename - name of the downloaded MIDlet suite jar file;
 *     suiteName - name of the suite;
 *     suiteVendor - vendor of the suite;
 *     authPath - authPath if signed, the authorization path starting
 *                with the most trusted authority;
 *     domain - security domain of the suite;
 *     trusted - true if suite is trusted;
 *     verifyHash - may contain hash value of the suite with
 *                  preverified classes or may be NULL;
 *     jadProps - properties given in the JAD as an array of strings in
 *                key/value pair order, can be null if jadUrl is null
 *     jarProps - properties of the manifest as an array of strings
 *                in key/value pair order
 * </pre>
 *
 * @param pSuiteSettings structure containing the following information:<br>
 * <pre>
 *     permissions - permissions for the suite;
 *     pushInterruptSetting - defines if this MIDlet suite interrupt
 *                            other suites;
 *     pushOptions - user options for push interrupts;
 *     suiteId - unique ID of the suite, must be equal to the one given
 *               in installInfo;
 *     boolean enabled - if true, MIDlet from this suite can be run;
 * </pre>
 *
 * @param pSuiteData structure containing the following information:<br>
 * <pre>
 *     suiteId - unique ID of the suite, must be equal to the value given
 *               in installInfo and suiteSettings parameters;
 *     storageId - ID of the storage where the MIDlet should be installed;
 *     numberOfMidlets - number of midlets in the suite;
 *     displayName - the suite's name to display to the user;
 *     midletToRunClassName - the midlet's class name if the suite contains
 *                            only one midlet, ignored otherwise;
 *     iconName - name of the icon for this suite.
 * </pre>
 *
 * @return status ALL_OK for success else an error code
 */
MIDPError
midp_store_suite(const MidpInstallInfo* pInstallInfo,
                 const MidpSuiteSettings* pSuiteSettings,
                 const MidletSuiteData* pSuiteData);

#ifdef __cplusplus
}
#endif

#endif /* _SUITESTORE_INSTALLER_H_ */