suitestore_common.h

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

#if ENABLE_DYNAMIC_COMPONENTS
/**
 * Converts the given component ID to pcsl_string.
 * NOTE: this function returns a pointer to the static buffer!
 *
 * @param value component id to convert
 * @return pcsl_string representation of the given component id
 */
const pcsl_string* midp_componentid2pcsl_string(ComponentIdType value);
#endif

/**
 * Tells if a suite exists.
 *
 * @param suiteId ID of a suite
 *
 * @return ALL_OK if a suite exists,
 *         NOT_FOUND if not,
 *         OUT_OF_MEMORY if out of memory or IO error,
 *         IO_ERROR if IO error,
 *         SUITE_CORRUPTED_ERROR if suite is found in the list,
 *         but it's corrupted
 */
MIDPError midp_suite_exists(SuiteIdType suiteId);

/**
 * Gets location of the class path for the suite with the specified suiteId.
 *
 * Note that memory for the in/out parameter classPath is
 * allocated by the callee. The caller is responsible for
 * freeing it using pcsl_mem_free().
 *
 * @param suiteId The application suite ID
 * @param storageId storage ID, INTERNAL_STORAGE_ID for the internal storage
 * @param checkSuiteExists true if suite should be checked for existence or not
 * @param classPath The in/out parameter that contains returned class path
 * @return error code that should be one of the following:
 * <pre>
 *     ALL_OK, OUT_OF_MEMORY, NOT_FOUND,
 *     SUITE_CORRUPTED_ERROR, BAD_PARAMS
 * </pre>
 */
MIDPError midp_suite_get_class_path(SuiteIdType suiteId,
                                    StorageIdType storageId,
                                    jboolean checkSuiteExists,
                                    pcsl_string *classPath);

#if ENABLE_DYNAMIC_COMPONENTS
/**
 * Tells if a component exists.
 *
 * @param componentId ID of a component
 *
 * @return ALL_OK if a component exists,
 *         NOT_FOUND if not,
 *         OUT_OF_MEMORY if out of memory or IO error,
 *         IO_ERROR if IO error,
 *         SUITE_CORRUPTED_ERROR if component is found in the list,
 *         but it's corrupted
 */
MIDPError midp_component_exists(ComponentIdType componentId);

/**
 * Gets location of the class path for the component
 * with the specified componentId.
 *
 * Note that memory for the in/out parameter classPath is
 * allocated by the callee. The caller is responsible for
 * freeing it using pcsl_mem_free().
 *
 * @param componentId The ID of the component
 * @param suiteId The application suite ID
 * @param storageId storage ID, INTERNAL_STORAGE_ID for the internal storage
 * @param checkComponentExists true if the component should be checked for
                               existence or not
 * @param pClassPath The in/out parameter that contains returned class path
 * @return error code that should be one of the following:
 * <pre>
 *     ALL_OK, OUT_OF_MEMORY, NOT_FOUND,
 *     SUITE_CORRUPTED_ERROR, BAD_PARAMS
 * </pre>
 */
MIDPError
midp_suite_get_component_class_path(ComponentIdType componentId,
                                    SuiteIdType suiteId,
                                    StorageIdType storageId,
                                    jboolean checkComponentExists,
                                    pcsl_string *pClassPath);
#endif /* ENABLE_DYNAMIC_COMPONENTS */

#if ENABLE_MONET
/**
 * Only for MONET--Gets the class path to binary application image
 * for the suite with the specified MIDlet suite id.
 *
 * It is different from "usual" class path in that class path points to a
 * jar file, while this binary application image path points to a MONET bundle.
 *
 * Note that memory for the in/out parameter classPath is
 * allocated by the callee. The caller is responsible for
 * freeing it using pcsl_mem_free().
 *
 * @param suiteId The application suite ID
 * @param storageId storage ID, INTERNAL_STORAGE_ID for the internal storage
 * @param checkSuiteExists true if suite should be checked for existence or not
 * @param classPath The in/out parameter that contains returned class path
 * @return  error code that should be one of the following:
 * <pre>
 *     ALL_OK, OUT_OF_MEMORY, NOT_FOUND,
 *     SUITE_CORRUPTED_ERROR, BAD_PARAMS
 * </pre>
*/
MIDPError midp_suite_get_bin_app_path(SuiteIdType suiteId,
                                      StorageIdType storageId,
                                      pcsl_string *classPath);
#endif

/**
 * Gets location of the cached resource with specified name
 * for the suite with the specified suiteId.
 *
 * Note that when porting memory for the in/out parameter
 * filename MUST be allocated  using pcsl_mem_malloc().
 * The caller is responsible for freeing the memory associated
 * with filename parameter.
 *
 * @param suiteId       The application suite ID
 * @param storageId     storage ID, INTERNAL_STORAGE_ID for the internal storage
 * @param pResourceName Name of the cached resource
 * @param pFileName     The in/out parameter that contains returned filename
 * @return error code that should be one of the following:
 * <pre>
 *     ALL_OK, OUT_OF_MEMORY, NOT_FOUND,
 *     SUITE_CORRUPTED_ERROR, BAD_PARAMS
 * </pre>
 */
MIDPError
midp_suite_get_cached_resource_filename(SuiteIdType suiteId,
                                        StorageIdType storageId,
                                        const pcsl_string * pResourceName,
                                        pcsl_string * pFileName);

/**
 * Retrieves an ID of the storage where the midlet suite with the given suite ID
 * is stored.
 *
 * @param suiteId The application suite ID
 * @param pSuiteId [out] receives an ID of the storage where the suite is stored
 *
 * @return error code (ALL_OK if successful)
 */
MIDPError
midp_suite_get_suite_storage(SuiteIdType suiteId, StorageIdType* pStorageId);

/**
 * Retrieves an ID of the folder where the midlet suite with the given suite ID
 * is stored.
 *
 * @param suiteId The application suite ID
 * @param pFolderId [out] receives an ID of the folder where the suite is stored
 *
 * @return error code (ALL_OK if successful)
 */
MIDPError
midp_suite_get_suite_folder(SuiteIdType suiteId, FolderIdType* pFolderId);

/**
 * If the suite exists, this function returns a unique identifier of
 * MIDlet suite. Note that suite may be corrupted even if it exists.
 * If the suite doesn't exist, a new suite ID is created.
 *
 * @param vendor name of the vendor that created the application, as
 *          given in a JAD file
 * @param name name of the suite, as given in a JAD file
 * @param pSuiteId [out] receives the platform-specific suite ID of the
 *          application given by vendor and name, or UNUSED_SUITE_ID
 *          if suite does not exist, or out of memory error occured,
 *          or suite is corrupted.
 *
 * @return  ALL_OK if suite found,
 *          NOT_FOUND if suite does not exist (so a new ID was created),
 *          other error code in case of error
 */
MIDPError
midp_get_suite_id(const pcsl_string* vendor, const pcsl_string* name,
                  SuiteIdType* pSuiteId);

#if ENABLE_DYNAMIC_COMPONENTS
/**
 * If the dynamic component exists, this function returns a unique identifier
 * of the component. Note that the component may be corrupted even if it exists.
 * If the component doesn't exist, a new component ID is created.
 *
 * @param vendor name of the vendor that created the component, as
 *        given in a JAD file
 * @param name name of the component, as given in a JAD file
 * @param pComponentId [out] receives the platform-specific component ID of
 *        the component given by vendor and name, or UNUSED_COMPONENT_ID
 *        if component does not exist, or out of memory error occured,
 *        or component is corrupted.
 *
 * @return  ALL_OK if suite found,
 *          NOT_FOUND if component does not exist (so a new ID was created),
 *          other error code in case of error
 */
MIDPError
midp_get_component_id(const pcsl_string* vendor, const pcsl_string* name,
                      ComponentIdType* pComponentId);
#endif /* ENABLE_DYNAMIC_COMPONENTS */

/**
 * Gets the properties of a MIDlet suite to persistent storage.
 * <pre>
 * The format of the properties file will be:
 * <number of strings as int (2 strings per property)>
 *    {repeated for each property}
 *    <length of a property key as int>
 *    <property key as jchars>
 *    <length of property value as int>
 *    <property value as jchars>
 * </pre>
 *
 *
 * Note that memory for the strings inside the returned MidpProperties
 * structure is allocated by the callee, and the caller is
 * responsible for freeing it using midp_free_properties().
 *
 * @param suiteId ID of the suite
 *
 * @return properties in a pair pattern of key and value,
 * use the status macros to check the result. A SUITE_CORRUPTED_ERROR
 * is returned as a status of MidpProperties when suite is corrupted
 */
MidpProperties midp_get_suite_properties(SuiteIdType suiteId);

/**
 * Find and return the property the matches the given key.
 * The returned value need not be freed because it resides
 * in an internal data structure.
 *
 * @param pProperties property list
 * @param key key of property to find
 *
 * @return a pointer to the property value,
 *         or to PCSL_STRING_NULL if not found.
 */
pcsl_string*
midp_find_property(MidpProperties* pProperties, const pcsl_string* key);

/**
 * Free a list of properties. Does nothing if passed NULL.
 *
 * @param pProperties property list
 */
void midp_free_properties(MidpProperties* pProperties);

/**
 * Retrieves the specified property value of the suite.
 *
 * IMPL_NOTE: this functions is introduced instead of 3 functions above.
 *
 * @param suiteId [in]  unique ID of the MIDlet suite
 * @param pKey    [in]  property name
 * @param pValue  [out] buffer to conatain returned property value
 *
 * @return ALL_OK if no errors,
 *         BAD_PARAMS if some parameter is invalid,
 *         NOT_FOUND if suite was not found,
 *         SUITE_CORRUPTED_ERROR if the suite is corrupted
 */
MIDPError
midp_get_suite_property(SuiteIdType suiteId,
                        const pcsl_string* pKey,
                        pcsl_string* pValue);

#ifdef __cplusplus
}
#endif

#endif /* _SUITESTORE_COMMON_H_ */