Bundle Manager
[System]

Detailed Description

The Bundle Manager is a system framework designed to coordinate and control the installation, and removal of software components, including applications and shared libraries, for various target subsystems, including the ALP native application format.

It is intended that the Bundle Manager provide the mechanism to install and track applications for other executable systems, as a 68K compatiblity environment, or Java apps.

The Bundle Manager APIs operate on three levels:

Bundle Indexes: every bundle present in the system has a unique index number, and index values will not be re-used. These indexes are stored in variables of type AlpBundle. You'll use bundle indexes to iterate over available bundles, retrieve metadata, and generally work across multiple bundles.

Bundle Refs: in order to operate on the contents of a bundle, it must be opened. This gives back a handle, stored in a variable of type AlpBundleRef. Many operations can only be performed on a bundle if it is open. (Generally, the contents of a bundle are only accessible while it is open. Other information, such as metadata, can be accessed if it isn't open.) You'll use bundle refs to work within a particular bundle. Opening a bundle to get a ref is a potentially expensive operation (consuming time, memory, limited resources, etc.) so you want to do this only when you have to.

Bundle Names: each bundle has a supplied name of some sort. Bundles can be retrieved by name. However, there can be conflicts (bundles of the same name, perhaps installed on separate locations on the system). If there are conflicts, one bundle is always 'elected' to respond to the name, based on conflict resolution rules. The name of a bundle is text, and is intended as a symbolic reference. You'll use bundle names to retrieve a bundle by a symbolic name, probably as part of the your program's resource material.

There are some other concepts used by the Bundle Manager:

Schemes: each type of bundle is considered a distinct 'scheme'. The ALP native appliacation format is the 'bar' scheme.

Stores: each bundle is stored in a particular location (perhaps a folder in a file-system). A 'store' is a name for such a location.

Images: one of the characteristics of a bundle is that it can be put into a flattened format for transmitting off of the device, to a another device, "beamed" via IR, attached to e-mail, downloaded off the web, etc. An "image" is flat file containing a bundle.

Metadata: information about a bundle is called "metadata". This includes material retrieved from the bundle's header/manifest/etc., as well as dynamic information about the actual use of the bundle (ref-count, system paths, etc.) Metadata for a bundle can be retrieved without opening the bundle.

Properties: a property is generic (but structured) material associated with a bundle. In the case of ALP native bundles, the properties are retrieved from arbitray XML in the bundle's manifest. Properties are intended for customization by the developer, representing arbitray information about a bundle. Various ALP components may rely on particular properties, such as the Application Manager using the "application" property. Properties for a bundle can be retrieved without opening the bundle.

URLs: various naming concepts used by the Bundle Manager are designed to be represented as text, which can be fitted together into standard URL syntax. To give a quick example of some of the possibilities:

                bar:com.access.apps.memo
                bar:com.access.apps.memo/ListView.xml
                bar:com.access.apps.memo/libalp_memo.so?main
                bar:com.access.apps.memo/^p/application/icon

These represent scheme:name/path?entry, as will be described in the API reference. Generally, you don't need to use URLs with the Bundle Manager APIs, however there are a few routines which benefit from them, and give a lot of flexibility if they are used.

ALP native bundles

ALP native bundles are represented as folders or bar files which contain a Manifest.xml at its root.

The Manifest must have an outer-most <manifest> element, which can have these attributes:

name: this attribute is required, and contains the name of the bundle. It should not start with "bar:", as that part of the name is implied.

version: this attribute is optional, and if present should be an integer. If not present, the bundle version is considered to be 0.

arch: this attribute is optional, and if present should be a string indicating which architecture this bundle is intended for.

desired_filename: this attribute is optional, and if present indicates the file name which should be used to convert the bundle to an image file. The name given will have the ".bar" extension appended to it.

searchpath: this attribute is optional. If present, it should be a string in the form of a set of colon separate path prefixes, potentially containing "^l" to indicate a locale fill-point. This affects how localized resources are searched for. If not present, it defaults to /rsc/locale/^l/^f:/rsc/^f:/.

textdomain: this attribute is optional. If present, it defines the gettext omain applied by default to code running from this bundle. It should be a string potentially containing "^n" or "^N". The former is mapped to the bundle name without scheme ("com.companyname.appname"), while the latter is mapped to the complete bundle name ("bar:com.companyname.appname"). If not present, this attribute defaults to bar-^n.

bindtextdomain: this attribute is optional. If present, it defines the directory the gettext domain is bound to. It should be a string which defines a path relative to the base of the bundle. If not present, this attribute defaults to rsc.

The rest of the manifest should be in this form:

  <manifest name="foo.bar" searchpath="/share/^l/:/">
   <a>
     <b>1</b>
     <c>2</c>
   </a>
   <a>
     <x></x>
   </a>
   <other>
      <somevalue/>
   </other>
  </manifest>

Any elements within the manifest at the third level ("b", "c", and "x" in the above example) will be registered as bundle "properties", specifically:

   property "a", #0, key "b" -> "1"
                     key "c" -> "2"
   property "a", #1, key "x" -> ""
   property "other", #0, key "somevalue" -> ""

Any second-level elements not containing third-level elements, or any elements otherwise not conforming, will be ignored for the purpose of generating bundle properties. They won't prevent the bundle from being accepted, however.

Two properties have specific impact on the support for native bundles:

    <reference>
      <to>bundle-name</to>
      <optional/>
    </reference>

Any "reference" properties present will indicate that this bundle has a dependency on another bundle, particularly regarding use of shared libraries exported by the other bundle. The other bundle will automatically be opened when this bundle is opened. If the "optional" element isn't present, then this bundle cannot be opened if the one it is dependant on isn't present.

    <export>
       <library>somelib.so</library>
       <as>lib_somelib.so.3</as>
    </export>

Or

    <export>
       <classpath>lib/myclass.jar</classpath>
    </export>

The "library" syntax will cause a library exported from this bundle to be available whenever the bundle is open. The optional "as" element changes the name used for the exported version of the library.

The "classpath" syntax adds an entry (either a folder or .jar file) to the CLASSPATH environment variable while the bundle is open.

Either "export" element can be repeated to export multiple things.

The resource files associated with ALP native bundles map directly to the contents of the bundle's folder. A path starting with a slash is a "fixed path", and matches only that exact file within the bundle: /rsc/MyView.xml. A path starting without a slash is looked up through the locale search path, which can translate "MyView.xml" into "/rsc/en_US/MyView.xml", as appropriate.

Note that the use of a leading slash to distinguish fixed paths from localized paths means that you might need to use two slashes in URL syntax:

   bar:com.access.apps.memo//my/filename

There is one "magic" resource syntax specifically supported by ALP native bundles: the translation syntax is:

   ^t/Some string

This "path" will be retrieved by taking the part of the path after the slash, and feeding it through gettext() to perform a translation to the current locale. The result of the translation is considered the "contents" of the resource.

In URL syntax:

   bar:com.access.apps.memo/^t/MemoPad


Data Structures

struct  _AlpBundle
 Data type used to refer to a particular bundle The AlpBundle type is a short integral type used to index available bundles. An AlpBundle value will be good until (reset?). (If a bundle is deleted, the AlpBundle value will not be immediately reused). Any routine called with an invalid AlpBundle value will fail. Using an invalid AlpBundle value will not cause any alp_bundle routine to crash. More...
struct  _AlpBundleProgressiveData
struct  _AlpNotifyEventBundleCopy
struct  _AlpNotifyEventBundleDelete
struct  _AlpNotifyEventBundleMove
struct  _AlpNotifyEventBundleNameAdded
struct  _AlpNotifyEventBundleNameChanged
struct  _AlpNotifyEventBundleNameRemoved
struct  _AlpNotifyEventBundleRegister
struct  _AlpNotifyEventBundleResetEverything
struct  _AlpNotifyEventBundleUnregister
struct  AlpBundleEntrypointClosure

Miscellaneous and localization assistance

#define alp_bundle_acquire_glade_xml(url, root)
#define ALP_BUNDLE_FINGERTOUCH_RSC_PREFIX   "finger-"
 Prefix to resource names specific to finger-touch.
#define ALP_BUNDLE_FLAG_DELETE_EVERYTHING   1
 Flag to pass to some bundle manager routines to indicate all associated data should be removed.
#define ALP_BUNDLE_FLAG_OVERWRITE_DUPLICATE   128
 Flag to pass to some bundle manager routines to cause an image install to overwrite a bundle of the same name, if it exists.
#define alp_bundle_gettext(text)   dgettext(alp_bundle_ref_gettextdomain(alp_bundle_ref_me()), (text))
#define alp_bundle_ref_cgettext(ref, text, category)   dcgettext(alp_bundle_ref_gettextdomain((ref)), (text), (category)) \
#define alp_bundle_ref_gettext(ref, text)   dgettext(alp_bundle_ref_gettextdomain((ref)), (text)) \
alp_status_t alp_bundle_error (void)
gchar * alp_bundle_name (AlpBundle index)
const char * alp_bundle_ref_gettextdomain (AlpBundleRef ref)
const char * alp_bundle_ref_name (AlpBundleRef ref)
gchar * alp_bundle_saved_settings (AlpBundle index, const char *key)
gchar * alp_bundle_unsaved_settings (AlpBundle index, const char *key)

Operations on BundleRefs

#define ALP_BUNDLE_BAR_MANIFEST   "/Manifest.xml"
 Use this define as the path to retrieve the manifest from a bar bundle.
alp_status_t alp_bundle_close (AlpBundleRef ref)
 Close an open bundle Close a bundleref. No further access through the bundleref should be attempted. If all references to a bundle are closed, the bundle manager may disconnect or otherwise make the bundle unavailable for operations. Pathnames to ro bundle files may not function once it is closed.
AlpBundleRef alp_bundle_open (AlpBundle idx)
 Open a bundle Given a bundle index, open the bundle, making its contents available for use, until it is closed.
AlpBundleRef alp_bundle_ref_application ()
 Return a bundle ref to the running application Returns a bundle ref to the bundle which the running application was launched from.
AlpBundle alp_bundle_ref_bundle (AlpBundleRef ref)
 Return a bundle index given a bundle ref Returns a bundle index for a supplied bundle ref.
AlpBundleRef alp_bundle_ref_me ()
 Return a bundle ref to the running code Returns a bundle ref to the bundle which contains the code which invoked this function. Note that this function explicitly detects what routine it is being called from. Don't expect it to operate from a utility subroutine -- consider using a macro.
GIOChannel * alp_bundle_ref_ro_channel (AlpBundleRef ref, const char *path)
 Open a GIOChannel to retrieve a read-only file from a bundle.
alp_status_t alp_bundle_ref_ro_data (AlpBundleRef ref, const char *path, gchar **data, size_t *length)
 Retrieve a read-only file in a bundle as an allocated data block.
GList * alp_bundle_ref_ro_directory (AlpBundleRef ref, const char *path, gboolean recurse)
 Retrieve list of resources within a bundle.
gchar * alp_bundle_ref_ro_pathname (AlpBundleRef ref, const char *path)
 Retrieve a pathname for read-only file in a bundle.
gchar * alp_bundle_ref_ro_tempfile (AlpBundleRef ref, const char *path, gboolean keep, const char *ext)
 Create a temporary file with the contents of a read-only file in a bundle.
alp_status_t alp_bundle_tempfile_release (gchar *tempfile)
 Releases any storage associated with a tempfile returned from alp_bundle_ref_ro_tempfile().

Acquisition operations

These are all implemented as composites of other routines, really just conveniences.

The URLs allowed by these routines may have a scheme and bundle name and/or a path and/or a search entry for entrypoint selection.

That is, you can say:

        bar:bundle.name/resource/path
        /resource/path
        bar:bundle.name
        bar:bundle.name/library?function

An additional path syntax is available from the acquire routines to use bundle properties:

        bar:bundle.name/^p/application/icon

This has the affect of retrieving the value of the icon key of the application property of the bar:bundle.name bundle, and using that value as the name of another resource.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_CALLBACK(closure)   (((AlpBundleEntrypointClosure*)(closure))->callback)
 Retrieve the dlsym() function pointer held by the closure, if any.
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_DLHANDLE(closure)   (((AlpBundleEntrypointClosure*)(closure))->dlhandle)
 Retrieve the dlopen() handle held by the closure, if any.
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_PATH(closure)   (((AlpBundleEntrypointClosure*)(closure))->path)
 Retrieve the R/O library path used by setting up the closure, if any.
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_REF(closure)   (((AlpBundleEntrypointClosure*)(closure))->ref)
 Retrieve the AlpBundleRef held by the closure, if any.
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_RESULT_SIGNAL(closure)   (((AlpBundleEntrypointClosure*)(closure))->result_signal)
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_SYM(closure)   (((AlpBundleEntrypointClosure*)(closure))->sym)
 Retrieve the symbol name used by dlsym(), if any.
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_VERSION   1
GClosure * alp_bundle_acquire_entrypoint (const char *url, AlpBundleRef relativeRef)
 Get a function pointer to a shared library via a URL.
GIOChannel * alp_bundle_acquire_ro_channel (const char *url, AlpBundleRef relativeRef)
 Get an GIOChannel for a R/O file within a bundle via a URL.
alp_status_t alp_bundle_acquire_ro_data (const char *url, gchar **data, size_t *length, AlpBundleRef relativeRef)
 Get a block of data from the contents of a R/O file within a bundle via a URL.
gchar * alp_bundle_acquire_ro_pathname (const char *url, AlpBundleRef *openRef, AlpBundleRef relativeRef)
 Get a pathname to a R/O file within a bundle via a URL.
gchar * alp_bundle_acquire_ro_tempfile (const char *url, AlpBundleRef *openRef, gboolean keep, const char *ext, AlpBundleRef relativeRef)
 Get a temporary file for the contents of a R/O file within a bundle via a URL.
int alp_bundle_entrypoint_closure_execl (GClosure *closure, const char *arg,...)
int alp_bundle_entrypoint_closure_execve (GClosure *closure, char *const argv[], char *const envp[])
 Invoke a GClosure with command-line parameters from an array, return result.

Data types

#define ALP_BUNDLE_NULL   ((struct _AlpBundle){0})
 Constant which is a NULL AlpBundle value.
#define ALP_BUNDLE_REF_NULL   (NULL)
#define ALP_STATUS_BUNDLEMGR_CANCELED   (ALP_CLASS_BUNDLE | 0x00020000)
 Bundle Mgr operation canceled (eg. delete or copy).
#define ALP_STATUS_BUNDLEMGR_FAILURE   (ALP_CLASS_BUNDLE | 0x00010000)
 Generic failure.
typedef _AlpBundle AlpBundle
 Data type used to refer to a particular bundle The AlpBundle type is a short integral type used to index available bundles. An AlpBundle value will be good until (reset?). (If a bundle is deleted, the AlpBundle value will not be immediately reused). Any routine called with an invalid AlpBundle value will fail. Using an invalid AlpBundle value will not cause any alp_bundle routine to crash.
typedef _AlpBundleRef * AlpBundleRef
 Data type used as handle to an open bundle The AlpBundleRef type is a pointer to an opaque type, used as a handle to open bundles.
static gboolean alp_bundle_is_NULL (AlpBundle index)
 Test to see if an AlpBundle value is NULL.

Manifest Metadata

These constants define the names of common manifest metadata property lists.

#define ALP_BUNDLE_PROPERTY_APPLICATION   "application"
 The "application" manifest metadata indicates that the bundle contains an app.

Operations on Bundles

#define ALP_BUNDLE_RW_SAVED   "/saved/"
GList * alp_bundle_all_properties (AlpBundle index)
 Given a bundle index, return a list of property key hash tables or NULL if no properties exist.
AlpBundle alp_bundle_application ()
 Return a bundle index of the running application Returns a bundle index to the bundle which contains the launched ALP application.
AlpBundle alp_bundle_copy_to_store (AlpBundle bundle, const char *store, int flags)
 Copy a bundle to an active store This uses the bundle manager to copy a registered bundle from one store to another. The new copy will be registered along with the old one -- only one will have its name registered, and which one will depend on the particular stores.
alp_status_t alp_bundle_delete (AlpBundle bundle, int everything)
 Delete a bundle.
AlpBundle alp_bundle_locate_file (const char *filename)
 Identify open bundle containing a file Given a POSIX file path, this will attempt to identify an open bundle which matches that path. The supplied path can be the root of a folder, or any file or folder name within that folder (existing or not).
AlpBundle alp_bundle_me ()
 Return a bundle index of the bundle containing the running code Returns a bundle index to the bundle which contains the code which invoked this function. Note that this function explicitly detects what routine it is being called from. Don't expect it to operate from a utility subroutine -- consider using a macro.
GHashTable * alp_bundle_metadata (AlpBundle)
gchar * alp_bundle_metadata_value (AlpBundle index, const char *key)
 Return a the value for a metadata key of a bundle Given a bundle index and a key name, return the value of that key as an allocated string, or NULL if there is no such key.
AlpBundle alp_bundle_move_to_store (AlpBundle bundle, const char *store, int flags)
 Move a bundle to an active store This uses the bundle manager to move a registered bundle from one store to another.
GHashTable * alp_bundle_properties (AlpBundle index, const char *property, int which)
 Given a bundle index and a property name, return the key value hash table for that property.
gchar * alp_bundle_property_value (AlpBundle index, const char *property, int which, const char *key)
 Given a bundle index and a key name, return the value of that key as an allocated string, or NULL if there is no such key.
alp_status_t alp_bundle_rw_delete (AlpBundle index, const char *folder_path, gboolean itself)
 Delete some or all files within a bundles R/W data folder As a convenience, you can easily delete all of the R/W data for a bundle, or a subset of that data, using this routine. If the supplied file_path is empty (""), then all data will be removed, otherwise only data in a folder matching the supplied path.
gchar * alp_bundle_rw_pathname (AlpBundle index, const char *file_path, gboolean vivify)
 Returns the path to the R/W data folder for a bundle.

Bundle Types

These constants define the schemes for various bundle types.

#define ALP_BUNDLE_SCHEME_EXTENSION_BAR   ".bar"
 The common extension used for files containing ALP native bundles.
#define ALP_BUNDLE_SCHEME_EXTENSION_GVM   ".prc"
 The common extension used for files containing GVM bundles.
#define ALP_BUNDLE_SCHEME_EXTENSION_JAVA   ".jar"
 The common extension used for files containing Java bundles.
#define ALP_BUNDLE_SCHEME_MIMETYPE_BAR   "x-application/access-bar"
 The common mimetype used for files containing ALP native bundles.
#define ALP_BUNDLE_SCHEME_MIMETYPE_GVM   "application/vnd.palm"
 The common mimetype used for files containing GVM bundles.
#define ALP_BUNDLE_SCHEME_MIMETYPE_GVM_2   "application/x-pilot"
 A less common mimetype used for files containing GVM bundles.
#define ALP_BUNDLE_SCHEME_MIMETYPE_JAVA   "application/java-archive"
 The common mimetype used for files containing Java bundles (JAR files).
#define ALP_BUNDLE_SCHEME_MIMETYPE_JAVA_2   "text/vnd.sun.j2me.app-descriptor"
 The common mimetype used for files which are associated with Java bundles (JAD files).
#define ALP_BUNDLE_TYPE_BAR   "bar"
 The name of the native ALP bundle scheme, "bar".
#define ALP_BUNDLE_TYPE_GVM   "GHost"
 The GVM bundle type.
#define ALP_BUNDLE_TYPE_JAVA   "java"
 The Java bundle type.

Notifications

#define ALP_NOTIFY_EVENT_BUNDLE_COPY   "/alp/bundlemgr/copy_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_DELETE   "/alp/bundlemgr/delete_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_MOVE   "/alp/bundlemgr/move_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_ADDED   "/alp/bundlemgr/name_added"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_CHANGED   "/alp/bundlemgr/name_changed"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_REMOVED   "/alp/bundlemgr/name_removed"
#define ALP_NOTIFY_EVENT_BUNDLE_REGISTER   "/alp/bundlemgr/register_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_RESET_EVERYTHING   "/alp/bundlemgr/reset_everything"
#define ALP_NOTIFY_EVENT_BUNDLE_STORE_ADDED   "/alp/bundlemgr/store_added"
#define ALP_NOTIFY_EVENT_BUNDLE_STORE_REMOVED   "/alp/bundlemgr/store_removed"
#define ALP_NOTIFY_EVENT_BUNDLE_UNREGISTER   "/alp/bundlemgr/unregister_bundle"
typedef _AlpNotifyEventBundleCopy AlpNotifyEventBundleCopy
typedef _AlpNotifyEventBundleDelete AlpNotifyEventBundleDelete
typedef _AlpNotifyEventBundleMove AlpNotifyEventBundleMove
typedef _AlpNotifyEventBundleNameAdded AlpNotifyEventBundleNameAdded
typedef _AlpNotifyEventBundleNameChanged AlpNotifyEventBundleNameChanged
typedef _AlpNotifyEventBundleNameRemoved AlpNotifyEventBundleNameRemoved
typedef _AlpNotifyEventBundleRegister AlpNotifyEventBundleRegister
typedef _AlpNotifyEventBundleResetEverything AlpNotifyEventBundleResetEverything
typedef char AlpNotifyEventBundleStoreAdded []
typedef char AlpNotifyEventBundleStoreRemoved []
typedef _AlpNotifyEventBundleUnregister AlpNotifyEventBundleUnregister

Operations on Images

typedef _AlpBundleProgressiveData AlpBundleProgressiveData
 Tracks data for callback regarding progression of install or archive of bundle images An object of type AlpBundleProgressiveData is used to indicate to the alp_bundle_image_install() and alp_bundle_image_archive() routines that they should periodically invoke a callback function to let their caller know that the image creation/transfer process is proceeding.
enum  { ALP_BUNDLE_PROGRESSIVE_DATA_VERSION = 1 }
alp_status_t alp_bundle_image_archive (AlpBundle index, char **desired_filename, char **desired_mimetype, GIOChannel *image, AlpBundleProgressiveData *progress)
 Archive a bundle to an I/O channel Given a bundle, and a data sink specified by a GIOChannel, this routine will flatten a bundle into an image, and write it to that channel. This is the fundamental routine used to prepare bundles for sending outside the device. (e-mail, beaming, files, etc.).
AlpBundle alp_bundle_image_install (const char *provide_filename, const char *provide_mimetype, GIOChannel *image, const char *destination_store, int flags, GHashTable **metadata, GHashTable **properties, AlpBundleProgressiveData *progress)
 Install a bundle into the system from an I/O channel Given a data source specified by a GIOChannel, this routine will read a bundle from that source, and install it into a store in the system. This is the fundamental routine used to install new programs.
int alp_bundle_image_verify (const char *provide_filename, const char *provide_mimetype, GIOChannel *image, gboolean full_check, GHashTable **metadata, GHashTable **properties, AlpBundleProgressiveData *progress)
 Verify that a bundle image is somewhat undamaged, and get its metainfo.

Finding bundles

AlpBundle alp_bundle_by_name (const char *name)
 Get bundle index for a given name.
GList * alp_bundle_list_names (void)
 Return a list of all bundle names in the system.
GList * alp_bundle_list_properties (void)
 Return a list of all properties which are present in any bundle in the system.
GList * alp_bundle_list_schemes (void)
 Return a list of all valid bundle types the system supports.
GList * alp_bundle_list_stores (void)
 Return a list of all stores current available in the system.
GArray * alp_bundle_search (const char *name, gboolean named, const char *scheme, const char *store, const char *property)
 Search for bundles that match a set of criteria, including name, store, properties, type. This function returns zero, one, or more AlpBundle indexes for bundle which match a set of criteria. This is the fundamental routine for finding AlpBundle identifiers if you can't use alp_bundle_by_name(). If you want to retrieve all valid bundle indexes, use this routine with a set of NULL parameters.

Initialization

alp_status_t alp_bundle_fini (void)
 Shutdown (finalize) the bundle manager client library.
alp_status_t alp_bundle_init (void)
 Initialize the bundle manager client library. Needed if you are not running as an ALP application The bundle manager needs to be initialized before you can do anything with it. ALP applications normally run in an environment where the bundle manager is already initialized.

Scheme routines

gchar * alp_bundle_scheme_identify (const char *filename, const char *mimetype)
 Given a filename and/or mimetype, determine what bundle scheme is appropriate.
gchar * alp_bundle_scheme_value (const char *scheme, const char *key)
 Return a the value for a scheme description key Given a scheme name and a key name, return the value of that key as an allocated string, or NULL if there is no such key.
GHashTable * alp_bundle_scheme_values (const char *scheme)
 Return all data describing a scheme Given a scheme name, returns a hashtable containing keys and values describing the scheme.

Operations on Stores

GHashTable * alp_bundle_store (const char *store)
 Retrieve information about a store.
gchar * alp_bundle_store_value (const char *store, const char *key)
 Retrieve a particular information value about a store.

Define Documentation

#define alp_bundle_acquire_glade_xml (  url,
root   ) 
 

Value:

({                                                      \
  AlpBundleRef _ref;                                    \
  AlpBundleRef _me = alp_bundle_ref_me();               \
  gchar * _pathname = alp_bundle_acquire_ro_pathname((url), &_ref, _me);        \
  GladeXML * _result = glade_xml_new_with_domain(_pathname, (root), alp_bundle_ref_gettextdomain(_ref));        \
  g_free(_pathname);                                    \
  alp_bundle_close(_ref);                               \
  _result;                                              \
})
Utility macro to load a glade XML file from a bundle

Parameters:
[in] url URL to bundle including path to glade xml file
[in] root Name of root to start from, or NULL
Returns:
A GladeXML *

#define ALP_BUNDLE_BAR_MANIFEST   "/Manifest.xml"
 

Use this define as the path to retrieve the manifest from a bar bundle.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_CALLBACK (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->callback)
 

Retrieve the dlsym() function pointer held by the closure, if any.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_DLHANDLE (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->dlhandle)
 

Retrieve the dlopen() handle held by the closure, if any.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_PATH (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->path)
 

Retrieve the R/O library path used by setting up the closure, if any.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_REF (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->ref)
 

Retrieve the AlpBundleRef held by the closure, if any.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_RESULT_SIGNAL (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->result_signal)
 

After closure invocation, this will be zero on a successful invocation, less than zero for some internal errors, positive if an executable was invoked and terminated with a signal

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_SYM (  closure   )     (((AlpBundleEntrypointClosure*)(closure))->sym)
 

Retrieve the symbol name used by dlsym(), if any.

#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_VERSION   1
 

#define ALP_BUNDLE_FINGERTOUCH_RSC_PREFIX   "finger-"
 

Prefix to resource names specific to finger-touch.

#define ALP_BUNDLE_FLAG_DELETE_EVERYTHING   1
 

Flag to pass to some bundle manager routines to indicate all associated data should be removed.

#define ALP_BUNDLE_FLAG_OVERWRITE_DUPLICATE   128
 

Flag to pass to some bundle manager routines to cause an image install to overwrite a bundle of the same name, if it exists.

#define alp_bundle_gettext (  text   )     dgettext(alp_bundle_ref_gettextdomain(alp_bundle_ref_me()), (text))
 

Utility macro to retrieve a gettext localization from the current bundle

You might want to say:

        #define _(x) alp_bundle_gettext(x)

Parameters:
[in] text String to localize
Returns:
A char* which should not be freed

#define ALP_BUNDLE_NULL   ((struct _AlpBundle){0})
 

Constant which is a NULL AlpBundle value.

#define ALP_BUNDLE_PROPERTY_APPLICATION   "application"
 

The "application" manifest metadata indicates that the bundle contains an app.

#define alp_bundle_ref_cgettext (  ref,
text,
category   )     dcgettext(alp_bundle_ref_gettextdomain((ref)), (text), (category)) \
 

Utility macro to retrieve a gettext localization

Parameters:
[in] ref Bundle reference
[in] text String to localize
[in] category gettext category
Returns:
A char* which should not be freed

#define alp_bundle_ref_gettext (  ref,
text   )     dgettext(alp_bundle_ref_gettextdomain((ref)), (text)) \
 

Utility macro to retrieve a gettext localization

Parameters:
[in] ref Bundle reference
[in] text String to localize
Returns:
A char* which should not be freed

#define ALP_BUNDLE_REF_NULL   (NULL)
 

#define ALP_BUNDLE_RW_SAVED   "/saved/"
 

One R/W sub-folder is automatically backed up to the desktop. If you want data to be backed up, please use the ALP_BUNDLE_RW_SAVED path:

path = alp_bundle_rw_pathname(pkg, ALP_BUNDLE_RW_SAVED "mydata");

#define ALP_BUNDLE_SCHEME_EXTENSION_BAR   ".bar"
 

The common extension used for files containing ALP native bundles.

#define ALP_BUNDLE_SCHEME_EXTENSION_GVM   ".prc"
 

The common extension used for files containing GVM bundles.

#define ALP_BUNDLE_SCHEME_EXTENSION_JAVA   ".jar"
 

The common extension used for files containing Java bundles.

#define ALP_BUNDLE_SCHEME_MIMETYPE_BAR   "x-application/access-bar"
 

The common mimetype used for files containing ALP native bundles.

#define ALP_BUNDLE_SCHEME_MIMETYPE_GVM   "application/vnd.palm"
 

The common mimetype used for files containing GVM bundles.

#define ALP_BUNDLE_SCHEME_MIMETYPE_GVM_2   "application/x-pilot"
 

A less common mimetype used for files containing GVM bundles.

#define ALP_BUNDLE_SCHEME_MIMETYPE_JAVA   "application/java-archive"
 

The common mimetype used for files containing Java bundles (JAR files).

#define ALP_BUNDLE_SCHEME_MIMETYPE_JAVA_2   "text/vnd.sun.j2me.app-descriptor"
 

The common mimetype used for files which are associated with Java bundles (JAD files).

#define ALP_BUNDLE_TYPE_BAR   "bar"
 

The name of the native ALP bundle scheme, "bar".

#define ALP_BUNDLE_TYPE_GVM   "GHost"
 

The GVM bundle type.

#define ALP_BUNDLE_TYPE_JAVA   "java"
 

The Java bundle type.

#define ALP_NOTIFY_EVENT_BUNDLE_COPY   "/alp/bundlemgr/copy_bundle"
 

Name of notification sent when a bundle has is in the process of being copied. If a handler of this notification set bit 0 of the handled flag, the copy will be cancelled.

#define ALP_NOTIFY_EVENT_BUNDLE_DELETE   "/alp/bundlemgr/delete_bundle"
 

Name of notification sent when a bundle has is in the process of being deleted. If a handler of this notification set bit 0 of the handled flag, the deletion will be cancelled.

#define ALP_NOTIFY_EVENT_BUNDLE_MOVE   "/alp/bundlemgr/move_bundle"
 

Name of notification sent when a bundle has is in the process of being moved. If a handler of this notification set bit 0 of the handled flag, the move will be cancelled.

#define ALP_NOTIFY_EVENT_BUNDLE_NAME_ADDED   "/alp/bundlemgr/name_added"
 

Name of notification sent when new bundle name has appeared.

#define ALP_NOTIFY_EVENT_BUNDLE_NAME_CHANGED   "/alp/bundlemgr/name_changed"
 

Name of notification sent when a bundle name has changed to refer to a different bundle.

#define ALP_NOTIFY_EVENT_BUNDLE_NAME_REMOVED   "/alp/bundlemgr/name_removed"
 

Name of notification sent when a bundle name has been removed.

#define ALP_NOTIFY_EVENT_BUNDLE_REGISTER   "/alp/bundlemgr/register_bundle"
 

Name of notification sent when a bundle has been registered.

#define ALP_NOTIFY_EVENT_BUNDLE_RESET_EVERYTHING   "/alp/bundlemgr/reset_everything"
 

Name of notification sent when all bundle manager state has been lost

#define ALP_NOTIFY_EVENT_BUNDLE_STORE_ADDED   "/alp/bundlemgr/store_added"
 

Name of notification sent when a store has been added

#define ALP_NOTIFY_EVENT_BUNDLE_STORE_REMOVED   "/alp/bundlemgr/store_removed"
 

Name of notification sent when a store has been removed

#define ALP_NOTIFY_EVENT_BUNDLE_UNREGISTER   "/alp/bundlemgr/unregister_bundle"
 

Name of notification sent when a bundle has is in the process of being unregistered.

#define ALP_STATUS_BUNDLEMGR_CANCELED   (ALP_CLASS_BUNDLE | 0x00020000)
 

Bundle Mgr operation canceled (eg. delete or copy).

#define ALP_STATUS_BUNDLEMGR_FAILURE   (ALP_CLASS_BUNDLE | 0x00010000)
 

Generic failure.

Typedef Documentation

typedef struct _AlpBundle AlpBundle
 

Data type used to refer to a particular bundle The AlpBundle type is a short integral type used to index available bundles. An AlpBundle value will be good until (reset?). (If a bundle is deleted, the AlpBundle value will not be immediately reused). Any routine called with an invalid AlpBundle value will fail. Using an invalid AlpBundle value will not cause any alp_bundle routine to crash.

Do not attempt to manipulate AlpBundle values numerically: always use values returned from alp_bundle_by_name() or alp_bundle_search().

An AlpBundle may be "NULL", meaning that it is a not a valid bundle index. This condition can be tested with alp_bundle_is_NULL().

Note:
This type is a structure primarily so other numeric values aren't accidentally used as AlpBundle indexes. If you want to step over each available bundle, use alp_bundle_search() with a set of NULL parameters to retrieve all valid bundle indexes.

typedef struct _AlpBundleProgressiveData AlpBundleProgressiveData
 

Tracks data for callback regarding progression of install or archive of bundle images An object of type AlpBundleProgressiveData is used to indicate to the alp_bundle_image_install() and alp_bundle_image_archive() routines that they should periodically invoke a callback function to let their caller know that the image creation/transfer process is proceeding.

The structure contains some fields that should be filled in by the caller, and other fields which will be filled in by either of the image routines.

Note that the fields filled in are only good for the duration of the image routine execution, and should only be retrieved from within the callback function. After the image routine returns, the fields will be zeroed.

To use this structure, create an object of the right size, and set version to ALP_BUNDLE_PROGRESSIVE_DATA_VERSION.

typedef struct _AlpBundleRef* AlpBundleRef
 

Data type used as handle to an open bundle The AlpBundleRef type is a pointer to an opaque type, used as a handle to open bundles.

typedef struct _AlpNotifyEventBundleCopy AlpNotifyEventBundleCopy
 

typedef struct _AlpNotifyEventBundleDelete AlpNotifyEventBundleDelete
 

typedef struct _AlpNotifyEventBundleMove AlpNotifyEventBundleMove
 

typedef struct _AlpNotifyEventBundleNameAdded AlpNotifyEventBundleNameAdded
 

typedef struct _AlpNotifyEventBundleNameChanged AlpNotifyEventBundleNameChanged
 

typedef struct _AlpNotifyEventBundleNameRemoved AlpNotifyEventBundleNameRemoved
 

typedef struct _AlpNotifyEventBundleRegister AlpNotifyEventBundleRegister
 

typedef struct _AlpNotifyEventBundleResetEverything AlpNotifyEventBundleResetEverything
 

typedef char AlpNotifyEventBundleStoreAdded[]
 

typedef char AlpNotifyEventBundleStoreRemoved[]
 

typedef struct _AlpNotifyEventBundleUnregister AlpNotifyEventBundleUnregister
 

Enumeration Type Documentation

anonymous enum
 

Enumerator:
ALP_BUNDLE_PROGRESSIVE_DATA_VERSION  Current version of progressive data structure. This will change if the structure is modified in future.

Function Documentation

GClosure* alp_bundle_acquire_entrypoint (  const char *  url,
AlpBundleRef  relativeRef
) 
 

Get a function pointer to a shared library via a URL.

Parameters:
[in] url A bundle URL or an absolute file:/// URL. If a bundle name is used, then a shared library within a bundle can be opened. The file path indicates the name of a shared library: if absent, then a name automatically derived for the particular bundle type will be used, e.g.
                                        bar:com.access.apps.calculator
is the same as 
                                        bar:com.access.apps.calculator/libalp_calculator.so

A symbol name can be supplied with '?' syntax:

                                        bar:bundle.name/lib_mylib.so?OtherEntry

The default symbol name is alp_main.

An alternate functionality is available: if the path names an executable instead of a shared library, the returned closure will invoke the executable as a child process.

URL may be NULL, if a relativeRef is supplied. If this is the case, all defaults will be used.

Parameters:
[in] relativeRef If supplied, and the URL does not have an absolute bundle name then this bundle ref is used as the bundle to apply the file path to. If NULL, then relative URLs will fail. It is acceptable (and intended) that a relativeRef be supplied even if the URL is absolute.
Returns:
A GClosure* object. If a shared library entrypoint was acquired, a marshaller is set up which assumes the function takes the parameters int arc, char **argv, char **envp, and returns an int. If an executable was acquired, a marshaller is set up to invoke the executable in a child process and return its status. In both cases, the marshaller expects three arguments (int, char**, char **), corresponding to argc, argv, and envp, and returns an integer status value.
Note:
The returned GClosure* keeps a reference on the bundle containing the entrypoint. The bundle will be opened in the process of obtaining the GClosure (if it was not already open), and the bundle will remain open until the GClosure is freed with g_closure_unref().
The bundle references are managed in such a way that you do not need additional unrefs due to using this function. If you opened a bundle to get a ref to pass as the relativeRef parameter, you should close that ref after using this routine. If the relative ref is used by the closure, an additional refcount will be made.

Example of usage:
        AlpBundleRef myRef = alp_bundle_open(myBundleName);
        GClosure * myRoutine = alp_bundle_acquire_entrypoint("/somelib?routine", myRef);
        alp_bundle_close(myRef);
        g_closure_invoke(myRoutine, ...);
        g_close_unref(myRoutine);

GIOChannel* alp_bundle_acquire_ro_channel (  const char *  url,
AlpBundleRef  relativeRef
) 
 

Get an GIOChannel for a R/O file within a bundle via a URL.

This routine returns the pathname to a bundle resource. This only operates for some bundle types, particularly ALP native bundles (bar). Other types may not support direct file access, preventing this routine from being used. In that case, please consider using other routines, such as acquire_ro_data or acquire_ro_tempfile.

Parameters:
[in] url A bundle URL or absolute file:/// URL. If a bundle name is used, then a file within a bundle can be located.
[in] relativeRef If supplied, and the URL does not have an absolute bundle name then this bundle ref is used as the bundle to apply the file path to. If NULL, then relative URLs will fail. It is acceptable (and intended) that a relativeRef be supplied even if the URL is absolute.
Returns:
A GIOChannel* or NULL. Free with g_io_channel_unref() when you are done with it.
Note:
The returned GIOChannel* keeps a reference on the bundle containing the file. The bundle will be opened in the process of obtaining the GIOChannel (if it was not already open), and the bundle will remain open until the GIOChannel is freed with g_io_channel_unref().
The bundle references are managed in such a way that you do not need additional unrefs due to using this function. If you opened a bundle to get a ref to pass as the relativeRef parameter, you should close that ref after using this routine. If the relative ref is used by the channel, an additional refcount will be made.

Example of usage:
        AlpBundleRef myRef = alp_bundle_open(myBundleName);
        AlpBundleRef outRef;
        GIOChannel * channel = alp_bundle_acquire_ro_channel("/somefile", myRef);
        alp_bundle_close(myRef);
        // process channel
        g_io_channel_unref(channel);

alp_status_t alp_bundle_acquire_ro_data (  const char *  url,
gchar **  data,
size_t *  length,
AlpBundleRef  relativeRef
) 
 

Get a block of data from the contents of a R/O file within a bundle via a URL.

Parameters:
[in] url A bundle URL or absolute file:/// URL. If a bundle name is used, then a file within a bundle can be located.
[out] data A pointer to a gchar* should be supplied. It will be filled in with the allocated data block, if the acquisition is successful.
[out] length A pointer to a size_t should be supplied, or NULL. If supplied, it will be filled in with the length of the R/O file.
[in] relativeRef If supplied, and the URL does not have an absolute bundle name then this bundle ref is used as the bundle to apply the file path to. If NULL, then relative URLs will fail. It is acceptable (and intended) that a relativeRef be supplied even if the URL is absolute.
Returns:
Non-zero status on a failure. On success, ALP_STATUS_OK (0) is returned, and the supplied *data argument will have been filled in with a newly allocated block containing the contents of the R/O file. There is guaranteed to be a NUL past its end, to make sure it is NUL terminated. When you are done with the data, free it with g_free().
Note:
If you opened a bundle to get a ref to pass as the relativeRef parameter you may close that ref after using this routine.
Example of usage:
        AlpBundleRef myRef = alp_bundle_open(myBundleName);
        AlpBundleRef outRef;
        gchar * data;
        alp_status_t result = alp_bundle_acquire_ro_data("/sometextfile", &data, NULL, myRef);
        // process data
        g_free(data);

gchar* alp_bundle_acquire_ro_pathname (  const char *  url,
AlpBundleRef *  openRef,
AlpBundleRef  relativeRef
) 
 

Get a pathname to a R/O file within a bundle via a URL.

Parameters:
[in] url A bundle URL or absolute file:/// URL. If a bundle name is used, then a file within a bundle can be located. This my be NULL if a relativeRef is supplied. If NULL then the pathname to the base of the bundle will be returned.
[out] openRef If a matching file is found in a bundle, then the bundle will be opened, and it's reference placed in *openRef. You should close this ref with alp_bundle_close() when you are done with the pathname. (A ref will be returned, even if the supplied relativeRef is used to locate the resource. Always close the returned ref, regardless of whether a relativeRef is supplied as input. That will assure the correct refcounts.) The openRef might be NULL if a file:/// URL is supplied.
[in] relativeRef If supplied, and the URL does not have an absolute bundle name then this bundle ref is used as the bundle to apply the file path to. If NULL, then relative URLs will fail. It is acceptable (and intended) that a relativeRef be supplied even if the URL is absolute.
Returns:
An allocated gchar* or NULL. Free with g_free() when you are done with it. Close the openRef with alp_bundle_close() as well. Do not rely on the pathname being accessible after alp_bundle_close() is invoked.
Example of usage:
        AlpBundleRef myRef = alp_bundle_open(myBundleName);
        AlpBundleRef outRef;
        gchar * pathname = alp_bundle_acquire_ro_pathname("/somefile", &outRef, myRef);
        alp_bundle_close(myRef);
        FILE * f = fopen(pathname, "r");
        // process f
        flcose(f);
        alp_bundle_close(outRef);

gchar* alp_bundle_acquire_ro_tempfile (  const char *  url,
AlpBundleRef *  openRef,
gboolean  keep,
const char *  ext,
AlpBundleRef  relativeRef
) 
 

Get a temporary file for the contents of a R/O file within a bundle via a URL.

Parameters:
[in] url A bundle URL or absolute file:/// URL. If a bundle name is used, then a file within a bundle can be located.
[out] openRef If a matching file is found in a bundle, then the bundle will be opened, and it's reference placed in *openRef. You should close this ref with alp_bundle_close() when you are done with the pathname. (A ref will be returned, even if the supplied relativeRef is used to locate the resource. Always close the returned ref, regardless of whether a relativeRef is supplied as input. That will assure the correct refcounts.) The openRef might be NULL if a file:/// URL is supplied.
[in] keep If true, the temporary file is gauranteed to remain accessible after the openRef bundle is closed.
[in] ext Not used. This parameter must be NULL.
[in] relativeRef If supplied, and the URL does not have an absolute bundle name then this bundle ref is used as the bundle to apply the file path to. If NULL, then relative URLs will fail. It is acceptable (and intended) that a relativeRef be supplied even if the URL is absolute.
Returns:
An allocated gchar* or NULL. The result points to a file name, which can be used for an open command. The form or contents of the name is not specified. When you are done with the name, it must be freed with alp_bundle_tempfile_release(). If keep is not true, then the file should be closed and released before the openRef bundle is closed.
Note:
The resulting temporary file should be released with alp_bundle_tempfile_release() to make sure resources are properly reclaimed. However, the temporary file will be removed if the program exits without releasing it.
If you acquired the tempfile without the keep parameter set to TRUE, release the tempfile before closing the outRef, otherwise the results are undefined.

Example of usage:
        AlpBundleRef myRef = alp_bundle_open(myBundleName);
        AlpBundleRef outRef;
        gchar * filename = alp_bundle_acquire_ro_tempfile("/somefile", &outRef, FALSE, NULL, myRef);
        alp_bundle_close(myRef);
        FILE * f = fopen(filename, "r");
        // process f
        flcose(f);
        alp_bundle_close(outRef);

GList* alp_bundle_all_properties (  AlpBundle  index  ) 
 

Given a bundle index, return a list of property key hash tables or NULL if no properties exist.

Parameters:
[in] index 
Returns:
An allocated list of allocated property hash tables. If NULL, either there were no properties supplied in the bundle or there was no memory available to hold the data. Use g_hash_table_destroy() to free space used for list item data and then use g_list_free() to free the list.
         GList *props = alp_bundle_all_properties (index);
         while (props) {
             GHashTable * prop = (GHashTable *)props->data;

             // find property name in hash table
             gchar *pname = (gchar *) g_hash_table_lookup (prop, "");

             // iterate over keys in hash table
             g_hash_table_foreach(prop, do_something_for_each_key_value, NULL);

             // done with property hash table so free it
             g_hash_table_destroy (prop);

             // advance to next property item in list
             props = g_list_next(props);
         }
         g_list_free (props); // done with list

AlpBundle alp_bundle_application (   ) 
 

Return a bundle index of the running application Returns a bundle index to the bundle which contains the launched ALP application.

Returns:
NULL bundle index if the code is not running from an ALP application, otherwise a valid bundle index.

AlpBundle alp_bundle_by_name (  const char *  name  ) 
 

Get bundle index for a given name.

Parameters:
[in] name This argument should be in the normal form of a bundle ID, i.e., a URL such as "bar:com.access.apps.Contacts". The name may be a full URL including path, etc.: that material will be ignored for purposes of finding a bundle by name.
Returns:
An AlpBundle index to a bundle with a matching name if one exists, or else a NULL AlpBundle value.

alp_status_t alp_bundle_close (  AlpBundleRef  ref  ) 
 

Close an open bundle Close a bundleref. No further access through the bundleref should be attempted. If all references to a bundle are closed, the bundle manager may disconnect or otherwise make the bundle unavailable for operations. Pathnames to ro bundle files may not function once it is closed.

Parameters:
[in] ref Bundleref to close
Returns:
non-zero if failed.

AlpBundle alp_bundle_copy_to_store (  AlpBundle  bundle,
const char *  store,
int  flags
) 
 

Copy a bundle to an active store This uses the bundle manager to copy a registered bundle from one store to another. The new copy will be registered along with the old one -- only one will have its name registered, and which one will depend on the particular stores.

Parameters:
[in] bundle index of bundle to copy
[in] store name of store to copy it to
[in] flags ALP_BUNDLE_FLAG flags regarding collisions
Returns:
AlpBundle index of the copy.
Note:
this routine is not intended to be used to get a copy of a bundle as a flattened image for sending to another system, placing on a media card, etc. Copying a bundle to an external store may have the effect of turning it into a file which can be transmitted, but the alp_bundle_image_*() routines are to be preferred for this purpose.

alp_status_t alp_bundle_delete (  AlpBundle  bundle,
int  everything
) 
 

Delete a bundle.

Parameters:
[in] bundle index of bundle to delete
[in] everything 1 to delete all associated data, including RW folder, global settings, etc., 0 otherwise
Returns:
Non-zero value if the deletion was not successful

int alp_bundle_entrypoint_closure_execl (  GClosure *  closure,
const char *  arg,
  ...
) 
 

Invoke a GClosure with command-line parameters from function parameters, return result

This routine is a convenience function to invoke a GClosure with a set of parameters resembling the C 'main' entry sequence:

    int (closure)(int argc, char *argv[], char *envp[])

This routine takes an arbitrary number of C parameters, packs them up and invokes the given closure. The result of the closure invocation is returned as an integer.

Parameters:
[in] closure A GClosure*, probably returned from alp_bundle_acquire_ro_entrypoint
[in] arg,... A set of strings to be passed to the closure. This list must be terminated with NULL.
Returns:
exit status

int alp_bundle_entrypoint_closure_execve (  GClosure *  closure,
char *const   argv[],
char *const   envp[]
) 
 

Invoke a GClosure with command-line parameters from an array, return result.

This routine is a convenience function to invoke a GClosure with a set of parameters resembling the C 'main' entry sequence:

    int (closure)(int argc, char *argv[], char *envp[])

This routine takes argv and evnvp array pointers, packs up their contents and invokes the given closure. The result of the closure invocation is returned as an integer.

Parameters:
[in] closure A GClosure*, probably returned from alp_bundle_acquire_ro_entrypoint
[in] argv An array of char*'s, which must be terminated with a NULL
[in] envp An array of char*'s, which must be terminated with a NULL -- or a NULL pointer. If NULL is passed, this routine will automatically use the global environ variable. If you want to pass an empty environment, you should construct an envp consisting of just a NULL value.
Returns:
exit status

alp_status_t alp_bundle_error (  void   ) 
 

Returns status of last failing alp_bundle routine.

Some Bundle Manager routines cannot return a detailed status value. Any Bundle Manager routine which fails (and returns and error value) will set an error status value which can be retrieved via this function.

Successfull operations do not clear this status -- it is only modified by failing functions. This function should not be used except immediately after a failing Bundle Manager routine.

Returns:
An alp_status_t value which won't be ALP_STATUS_OK

alp_status_t alp_bundle_fini (  void   ) 
 

Shutdown (finalize) the bundle manager client library.

If you explicitly initialized the bundle manager with alp_bundle_init(), you should use alp_bundle_fini(). This routine will decrement a refcount, and then shut down the bundle manager.

alp_status_t alp_bundle_image_archive (  AlpBundle  index,
char **  desired_filename,
char **  desired_mimetype,
GIOChannel *  image,
AlpBundleProgressiveData *  progress
) 
 

Archive a bundle to an I/O channel Given a bundle, and a data sink specified by a GIOChannel, this routine will flatten a bundle into an image, and write it to that channel. This is the fundamental routine used to prepare bundles for sending outside the device. (e-mail, beaming, files, etc.).

Parameters:
[in] index A valid AlpBundle index
[out] desired_filename If not NULL, this will be filled in with the filename that the bundle thinks it should have.
[out] desired_mimetype If not NULL, this will be filled in with the mimetype that the bundle thinks it should have.
[in] image A GIOChannel * referring to a channel which the bundle data should be written to. This channel should at least support WRITE operations, and more efficient operation may be possible if it supports SEEK, or READ, (SEEK being more important than READ). If NULL, this routine will attempt to fill in the desired_filename and desired_mimetype parameters, if supplied, but will not actually archive the bundle.
[in] progress If not NULL, this should be an AlpBundleProgressiveData object.
Returns:
Non-zero value if is was not possible to archive the bundle

AlpBundle alp_bundle_image_install (  const char *  provide_filename,
const char *  provide_mimetype,
GIOChannel *  image,
const char *  destination_store,
int  flags,
GHashTable **  metadata,
GHashTable **  properties,
AlpBundleProgressiveData *  progress
) 
 

Install a bundle into the system from an I/O channel Given a data source specified by a GIOChannel, this routine will read a bundle from that source, and install it into a store in the system. This is the fundamental routine used to install new programs.

Parameters:
[in] provide_filename If not NULL, this should be the filename that was supplied with the data source. It's possible that the name is neither relevant nor needed, but it can be supplied.
[in] provide_mimetype If not NULL, this should be the mimetype that was supplied with the data source. It's possible that the mimetype is neither relevant nor needed, but it can be supplied.
[in] image A GIOChannel * referring to a channel which the bundle data should be read from. This channel should at least support READ operations, and more efficient operation may be possible if it supports SEEK. WRITE will never be used.
[in] destination_store If not NULL, this should be the name of a store which the bundle should be placed on. If NULL, the system will pick a default, normally the internal store.
[in] flags 0, or ALP_BUNDLE_FLAG_OVERWRITE_DUPLICATES, if you want to allow erasure of an identically named bundle
[out] metadata If not NULL, then this pointer will be filled with a copy of the bundle metadata.
[out] properties If not NULL, then this pointer will be filled with a copy of the bundle properties
[in] progress If not NULL, this should be an AlpBundleProgressiveData object.
Returns:
An AlpBundle index if installation was successful, otherwise a NULL index.

int alp_bundle_image_verify (  const char *  provide_filename,
const char *  provide_mimetype,
GIOChannel *  image,
gboolean  full_check,
GHashTable **  metadata,
GHashTable **  properties,
AlpBundleProgressiveData *  progress
) 
 

Verify that a bundle image is somewhat undamaged, and get its metainfo.

This routine will verify that an uninstalled/unregistered image of a bundle (i.e., the contents of a .jar, .bar, or .prc file) fulfills some basic consistency checks, and will retrieve the static metainformation from that bundle.

This routine operates on a GIOChannel, so the bundle image can be read from a file, or from some other data-source, potentially a streaming source.

Parameters:
[in] provide_filename If not NULL, this should be the filename that was supplied with the data source. It's possible that the name is neither relevant nor needed, but it can be supplied.
[in] provide_mimetype If not NULL, this should be the mimetype that was supplied with the data source. It's possible that the mimetype is neither relevant nor needed, but it can be supplied.
[in] image A GIOChannel * referring to a channel which the bundle data should be read from. This channel should at least support READ operations, and more efficient operation may be possible if it supports SEEK. WRITE will never be used.
[in] full_check Set this gbool to FALSE if you want to skip expensive tests (such as complete file-system integrity checks). It is not recommended to do this if you don't know the bundle previously passed full verification.
[out] metadata If not NULL, then this pointer will be filled with a copy of the bundle metadata.
[out] properties If not NULL, then this pointer will be filled with a copy of the bundle properties
[in] progress If not NULL, this should be an AlpBundleProgressiveData object, filled in as described

alp_status_t alp_bundle_init (  void   ) 
 

Initialize the bundle manager client library. Needed if you are not running as an ALP application The bundle manager needs to be initialized before you can do anything with it. ALP applications normally run in an environment where the bundle manager is already initialized.

Use this routine if you want to support running in environments without an initialized bundle manager.

If the bundle manager is already initialized (in any mode), this will increment a refcount. Thus, it's safe to use from arbitrary code.

static gboolean alp_bundle_is_NULL (  AlpBundle  index  )  [inline, static]
 

Test to see if an AlpBundle value is NULL.

Parameters:
[in] index AlpBundle index to test
Returns:
TRUE if the AlpBundle index is NULL, i.e., doesn't represent a bundle

GList* alp_bundle_list_names (  void   ) 
 

Return a list of all bundle names in the system.

Returns:
a GList* containing allocated gchar*'s of available bundle names. Free this list with g_list_foreach(results, (GFunc)g_free, NULL); g_list_free(results);

GList* alp_bundle_list_properties (  void   ) 
 

Return a list of all properties which are present in any bundle in the system.

Returns:
a GList* containing allocated gchar*'s of all bundle properties present in the system. Free this list with g_list_foreach(results, (GFunc)g_free, NULL); g_list_free(results);

GList* alp_bundle_list_schemes (  void   ) 
 

Return a list of all valid bundle types the system supports.

All of these return a GList of allocated strings.

Returns:
a GList* containing allocated gchar*'s of valid bundle schemes. Free this list with g_list_foreach(results, (GFunc)g_free, NULL); g_list_free(results);

GList* alp_bundle_list_stores (  void   ) 
 

Return a list of all stores current available in the system.

Returns:
a GList* containing allocated gchar*'s of available stores. Free this list with g_list_foreach(results, (GFunc)g_free, NULL); g_list_free(results);

AlpBundle alp_bundle_locate_file (  const char *  filename  ) 
 

Identify open bundle containing a file Given a POSIX file path, this will attempt to identify an open bundle which matches that path. The supplied path can be the root of a folder, or any file or folder name within that folder (existing or not).

Parameters:
[in] filename 
Returns:
NULL bundle index if no appropriate bundle can be found.

AlpBundle alp_bundle_me (   ) 
 

Return a bundle index of the bundle containing the running code Returns a bundle index to the bundle which contains the code which invoked this function. Note that this function explicitly detects what routine it is being called from. Don't expect it to operate from a utility subroutine -- consider using a macro.

This routine identifies the caller, and determines if that caller is in library loaded from a bundle. If the immediate caller is not in a bundle, NULL will be returned.

Note:
This routine is only specified to operate with shared libraries inside bundles. Operation when invoked from an executable is unpredictable.
Returns:
NULL bundle index if the code is not running from an identifable bundle, otherwise a bundle index.

GHashTable* alp_bundle_metadata (  AlpBundle   ) 
 

gchar* alp_bundle_metadata_value (  AlpBundle  index,
const char *  key
) 
 

Return a the value for a metadata key of a bundle Given a bundle index and a key name, return the value of that key as an allocated string, or NULL if there is no such key.

Parameters:
[in] index A bundle index. May be invalid, in which case an error will be returned.
[in] key A key string. Results are undefined if this is NULL.
Returns:
An allocated string containing the value of the metadata field for the given key. If the value is empty, an empty string will be returned. If the key is not present, NULL will be returned. When you are done with the result, free it with g_free().

AlpBundle alp_bundle_move_to_store (  AlpBundle  bundle,
const char *  store,
int  flags
) 
 

Move a bundle to an active store This uses the bundle manager to move a registered bundle from one store to another.

Parameters:
[in] bundle index of bundle to move
[in] store name of store to move it to
[in] flags ALP_BUNDLE_FLAG flags regarding collisions
Returns:
AlpBundle index of the moved bundle. Do not assume any relationship between the original and new index. They may differ, or be identical.
Note:
this routine is not intended to be used to get a copy of a bundle as a flattened image for sending to another system, placing on a media card, etc. Moving a bundle to an external store may have the effect of turning it into a file which can be transmitted, but the alp_bundle_image_*() routines are to be preferred for this purpose.

Since the bundle is being moved between stores, and the elected bundle for a particular name depends on store, it is possible that if similarly named bundles exist on several stores, the bundle responding to a name could change after the move.

gchar* alp_bundle_name (  AlpBundle  index  ) 
 

Given a bundle index, this will retrieve the bundle's name

Parameters:
[in] index Bundle index to retrieve text domain for
Returns:
An allocated gchar* of the bundle name. This value should be freed with g_free() when you are done with it.

AlpBundleRef alp_bundle_open (  AlpBundle  idx  ) 
 

Open a bundle Given a bundle index, open the bundle, making its contents available for use, until it is closed.

Note that opening a bundle will automatically make sure that any bundles it requires are also opened -- if any requirements are not met that are not optional, the open will fail.

GHashTable* alp_bundle_properties (  AlpBundle  index,
const char *  property,
int  which
) 
 

Given a bundle index and a property name, return the key value hash table for that property.

Parameters:
[in] index 
[in] property 
[in] which An integer specifying the occurence of the property in the bundle for which to return key values.
Returns:
An allocated hash table containing the key values pairs associated with the specified property. Use g_hash_table_destroy() to free the space allocated for this table.

gchar* alp_bundle_property_value (  AlpBundle  index,
const char *  property,
int  which,
const char *  key
) 
 

Given a bundle index and a key name, return the value of that key as an allocated string, or NULL if there is no such key.

Parameters:
[in] index A bundle index. May be invalid, in which case an error will be returned.
[in] property 
[in] which 
[in] key A key string. Results are undefined if this is NULL.
Returns:
An allocated string containing the value of the property field for the given key. If the value is empty, an empty string will be returned. If the key is not present, NULL will be returned. When you are done with the result, free it with g_free().

AlpBundleRef alp_bundle_ref_application (   ) 
 

Return a bundle ref to the running application Returns a bundle ref to the bundle which the running application was launched from.

Note:
. This routine will return the same AlpBundleRef for each invocation from the same instance of application. This AlpBundleRef will be effectively global, and should not be closed with alp_bundle_close(). As such, it "leaks" and will not be closed until the application exits.
Returns:
NULL bundle ref if the code is not running from a launched application process, otherwise a bundle ref.

AlpBundle alp_bundle_ref_bundle (  AlpBundleRef  ref  ) 
 

Return a bundle index given a bundle ref Returns a bundle index for a supplied bundle ref.

Parameters:
[in] ref A bundle ref, or NULL.This routine has undefined behaviour if the ref is invalid.
Returns:
A bundle index. Will be NULL if the bundle ref is NULL.

const char* alp_bundle_ref_gettextdomain (  AlpBundleRef  ref  ) 
 

Given a bundle ref, this will retrieve its domain for gettext

Some bundle types (ALP native bundles -- "bar") support gettext for localization. For these types of bundles, you can retrieve a text domain.

Parameters:
[in] ref Bundle reference to retrieve text domain for
Returns:
A char* of the appropriate textdomain, or NULL. This value is owned by bundle manager, and should not be freed, or used after the bundle reference is closed.

AlpBundleRef alp_bundle_ref_me (   ) 
 

Return a bundle ref to the running code Returns a bundle ref to the bundle which contains the code which invoked this function. Note that this function explicitly detects what routine it is being called from. Don't expect it to operate from a utility subroutine -- consider using a macro.

This routine identifies the caller, and determines if that caller is in library loaded from a bundle. If the immediate caller is not in a bundle, NULL will be returned.

Note:
. This routine will return the same AlpBundleRef for each invocation from the same bundle. This AlpBundleRef will be effectively global, and should not be closed with alp_bundle_close(). As such, it "leaks" and will not be closed until the application exits. For this reason, if you want fine control over the lifetime of the bundle containing code (likely for a plugin), then code in such bundles should not use alp_bundle_ref_me(), and instead use alp_bundle_me(), and explictly get an AlpBundleRef via alp_bundle_open() -- that will also be more efficient, as the invocation of either alp_bundle_me() or alp_bundle_ref_me() is somewhat expensive, and the result ought to be cached if possible.
Returns:
NULL bundle ref if the code is not running from an identifable bundle, otherwise a bundle ref.

const char* alp_bundle_ref_name (  AlpBundleRef  ref  ) 
 

Given a bundle ref, this will retrieve the bundle's name

Parameters:
[in] ref Bundle reference to retrieve name for
Returns:
A char* of the bundle name. This value is owned by bundle manager, and should not be freed, or used after the bundle reference is closed.

GIOChannel* alp_bundle_ref_ro_channel (  AlpBundleRef  ref,
const char *  path
) 
 

Open a GIOChannel to retrieve a read-only file from a bundle.

Given a pathname referring to a file existing within a bundle, this routine will open it for reading, and seeking if possible, and return a GIOChannel to the caller.

If the pathname starts with a slash, then it is taken as a fixed path within the bundle. If it does not start with a slash, it will be looked up according to the bundle's search path.

Parameters:
[in] ref Valid AlpBundleRef
[in] path Path to file within bundle
Returns:
A GIOChannel * if the file could be found and opened, otherwise NULL. The result should be freed with g_io_channel_unref().
Note:
The returned channel includes a reference to the bundle the file comes from. This will keep the bundle open even if alp_bundle_close(ref) is invoked -- the bundle will not be closed until the GIOChannel* is also unref'd.

alp_status_t alp_bundle_ref_ro_data (  AlpBundleRef  ref,
const char *  path,
gchar **  data,
size_t *  length
) 
 

Retrieve a read-only file in a bundle as an allocated data block.

Given a pathname referring to a file existing within a bundle, this routine will load the file contents into a newly allocated data block.

If the pathname starts with a slash, then it is taken as a fixed path within the bundle. If it does not start with a slash, it will be looked up according to the bundle's search path.

Parameters:
[in] ref Valid AlpBundleRef
[in] path Path to file within bundle
[out] data Pointer to gchar * which will be filled in with the allocation for the file contents.
[out] length If not NULL, then this is a pointer to size_t which will be filled in with the size of the file contents.
Returns:
Non-zero value if it was not possible to retrieve the data
When you are done with the data, you should free it with g_free().

GList* alp_bundle_ref_ro_directory (  AlpBundleRef  ref,
const char *  path,
gboolean  recurse
) 
 

Retrieve list of resources within a bundle.

Given a pathname referring to a folder within a bundle, this routine will return a list of all items in that folder inside the bundle.

Parameters:
[in] ref Valid AlpBundleRef
[in] path Path to folder within bundle. For consistency, these paths should always start with a "/", so they cannot be considered search-path-relative. Use the path "/" to retrieve items from the root of a bundle.
[in] recurse TRUE to recurse all of the way down through sub-folders in the bundle, FALSE to only return items directly contained in the supplied folder path.
Returns:
A GList of allocate gchar* pointers, containing full paths for each item in the bundle at that folder. Items which are themselves folders will end in a slash. When you are done with the results, free the list with g_list_foreach(results, (GFunc)g_free, NULL); g_list_free(results);

gchar* alp_bundle_ref_ro_pathname (  AlpBundleRef  ref,
const char *  path
) 
 

Retrieve a pathname for read-only file in a bundle.

Given a pathname referring to a file existing within a bundle, this routine will convert it to an absolute path, suitable for use with normal C and POSIX calls.

If the pathname starts with a slash, then it is taken as a fixed path within the bundle. If it does not start with a slash, it will be looked up according to the bundle's search path.

Parameters:
[in] ref Valid AlpBundleRef
[in] path Path to file within bundle
Returns:
An allocated absolute pathname if the file could be located, otherwise NULL. The result should be freed with g_free().
Note:
The returned pathname is only valid as long as the bundle is open. You should not invoke alp_bundle_close(ref) until after you have finished using the file represented by the returned path.

gchar* alp_bundle_ref_ro_tempfile (  AlpBundleRef  ref,
const char *  path,
gboolean  keep,
const char *  ext
) 
 

Create a temporary file with the contents of a read-only file in a bundle.

Given a pathname referring to a file existing within a bundle, this routine will return the name of a temporary file suitable for retrieving the contents.

If the pathname starts with a slash, then it is taken as a fixed path within the bundle. If it does not start with a slash, it will be looked up according to the bundle's search path.

Parameters:
[in] ref Valid AlpBundleRef
[in] path Path to file within bundle
[in] keep True if the tempfile is going to be used after the bundle is closed
[in] ext Unsupported: must be NULL
Returns:
An allocated absolute pathname if the file could be located, otherwise NULL. The result should be freed with alp_bundle_ref_ro_tempfile_free().
Note:
The returned tempfile may only be valid as long as the bundle is open. You should not invoke alp_bundle_close(ref) until after you have finished using the file represented by the returned path.
This routine is distinguished from alp_bundle_ref_to_pathname() because it will always be able to return a file name, regardless of the particular bundle type -- if necessary, it will create a temporary file and copy the resource into it. This is also done if keep is true, so that the resource will be accessible after the bundle is closed.

alp_status_t alp_bundle_rw_delete (  AlpBundle  index,
const char *  folder_path,
gboolean  itself
) 
 

Delete some or all files within a bundles R/W data folder As a convenience, you can easily delete all of the R/W data for a bundle, or a subset of that data, using this routine. If the supplied file_path is empty (""), then all data will be removed, otherwise only data in a folder matching the supplied path.

Parameters:
[in] index 
[in] folder_path 
[in] itself If FALSE then only the contents of the named folder will be removed, and not the folder itself.
Returns:
Non-zero value if the deletion was not successfull

gchar* alp_bundle_rw_pathname (  AlpBundle  index,
const char *  file_path,
gboolean  vivify
) 
 

Returns the path to the R/W data folder for a bundle.

This routine will automatically make any folders necessary. I.e., a call to alp_bundle_rw_pathname(pkg, "a/b/c", TRUE); will gaurantee that the "a", and "a/b" folders exist, so that the "a/b/c" file can be created if it does not already exist.

Parameters:
[in] index 
[in] file_path 
[in] vivify If TRUE, then the path will be created if it does not already exist. If FALSE, NULL will be returned if the path does not exist. NULL may be returned for the empty path "", if the entire R/W data folder has never been accessed.
Returns:
An allocated string containg the desired path, assuming that the AlpBundle was valid. NULL otherwise. Free the result with g_free() when you are done with it.

gchar* alp_bundle_saved_settings (  AlpBundle  index,
const char *  key
) 
 

Given a bundle index, retrieve the matching saved global settings key

Saved settings are global settings specific to a bundle which survive even when the associated bundle is deleted. The settings are related to bundle name, so any bundles of the same name share the same saved global settings.

Parameters:
[in] index Bundle index to retrieve settings key for
[in] key Sub-key to use for specific settings. This may be empty or NULL, in which case the primary key for saved settings will be returned.
Returns:
An allocated gchar* of the appropriate global settings key. This value should be freed with g_free() when you are done with it.

gchar* alp_bundle_scheme_identify (  const char *  filename,
const char *  mimetype
) 
 

Given a filename and/or mimetype, determine what bundle scheme is appropriate.

If there's enough information to make a guess about the type of bundle represented by a filename and/or mimetype, this routine will return the matching scheme name.

The scheme name returned may not be correct, and this does not gaurantee that attempting to install such a named bundle with that scheme will succeed -- this is strictly a front-line convenience routine.

Parameters:
[in] filename Name of file, or NULL
[in] mimetype Mimetype, or NULL
Returns:
An allocated string containng the appropriate scheme name if one appears to be appropriate. NULL otherwise. When you are done with the result, free it with g_free();

gchar* alp_bundle_scheme_value (  const char *  scheme,
const char *  key
) 
 

Return a the value for a scheme description key Given a scheme name and a key name, return the value of that key as an allocated string, or NULL if there is no such key.

Parameters:
[in] scheme A scheme name. May be invalid, or NULL, in which case an error will be returned.
[in] key A key string. Results are undefined if this is NULL.
Returns:
An allocated string containing the value of the scheme field for the given key. If the value is empty, an empty string will be returned. If the key is not present, NULL will be returned. When you are done with the result, free it with g_free().

GHashTable* alp_bundle_scheme_values (  const char *  scheme  ) 
 

Return all data describing a scheme Given a scheme name, returns a hashtable containing keys and values describing the scheme.

As an example, the "bar" scheme has "extension" and "mimetype" keys. The value for the "extension" key is ".bar".

Parameters:
[in] scheme A scheme name. May be an invalid scheme name or NULL, in which case an error will be returned.
Returns:
An GHashTable containing allocate gchar* keys and allocated gchar* values. If the scheme isn't valid, NULL will be returned.
When you are done with the result, free it with g_hash_table_destroy().

GArray* alp_bundle_search (  const char *  name,
gboolean  named,
const char *  scheme,
const char *  store,
const char *  property
) 
 

Search for bundles that match a set of criteria, including name, store, properties, type. This function returns zero, one, or more AlpBundle indexes for bundle which match a set of criteria. This is the fundamental routine for finding AlpBundle identifiers if you can't use alp_bundle_by_name(). If you want to retrieve all valid bundle indexes, use this routine with a set of NULL parameters.

Parameters:
[in] name A bundle name (of form "type:id", such as "bar:com.access.apps.Contacts"). May be NULL if you want to search for a bundle with any name. To search for a bundle of a particular type, but not name, use the scheme parameter. The name may be a full URL including path, etc.: that material will be ignored for purposes of finding a bundle by name.
[in] named TRUE if only named bundles should be returned, FALSE if you don't want to restrict the results.
[in] scheme A scheme name, such as "bar". May be NULL if you don't want to restrict the search results by scheme type.
[in] store A store name. May be NULL if you don't want to restrict the search results by store.
[in] property A property name. If supplied, the search will only return bundles which have a property of the given name. If NULL, then the results will not be restricted by properties.
Returns:
A GArray of AlpBundle values. If there were no results, a GArray will be returned, which is empty. NULL will be retuned if there is an actual error. In order to free the results, use the g_array routine g_array_free() with a second argument (free_segment) of FALSE to free the returned array.
Example




//!

GHashTable* alp_bundle_store (  const char *  store  ) 
 

Retrieve information about a store.

gchar* alp_bundle_store_value (  const char *  store,
const char *  key
) 
 

Retrieve a particular information value about a store.

alp_status_t alp_bundle_tempfile_release (  gchar *  tempfile  ) 
 

Releases any storage associated with a tempfile returned from alp_bundle_ref_ro_tempfile().

This routine should be used when you are done with a tempfile. It'll take care of releasing any storage (file, memory, heap, etc.) associated with a tempfile.

Parameters:
[in] tempfile A value returned from a call to alp_bundle_ref_ro_tempfile()
Returns:
Sucess or failure

gchar* alp_bundle_unsaved_settings (  AlpBundle  index,
const char *  key
) 
 

Given a bundle index, retrieve the matching unsaved global settings key

Unsaved settings are global settings specific to a bundle which are deleted when the associated bundle is deleted. The settings are related to bundle name, so any bundles of the same name share the same unsaved global settings.

Parameters:
[in] index Bundle index to retrieve settings key for
[in] key Sub-key to use for specific settings. This may be empty or NULL, in which case the primary key for unsaved settings will be returned.
Returns:
An allocated gchar* of the appropriate global settings key. This value should be freed with g_free() when you are done with it.

Generated on Wed Jul 30 07:06:44 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.