Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

bundlemgr.h File Reference

#include <hiker/types.h>
#include <glib.h>
#include <glib-object.h>

Go to the source code of this file.

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. More...
struct  _AlpBundleProgressiveData
struct  AlpBundleEntrypointClosure
struct  _AlpNotifyEventBundleDelete
struct  _AlpNotifyEventBundleMove
struct  _AlpNotifyEventBundleCopy
struct  _AlpNotifyEventBundleRegister
struct  _AlpNotifyEventBundleUnregister
struct  _AlpNotifyEventBundleResetEverything
struct  _AlpNotifyEventBundleNameAdded
struct  _AlpNotifyEventBundleNameRemoved
struct  _AlpNotifyEventBundleNameChanged

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_FAILURE   (ALP_CLASS_BUNDLEMGR | 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.
typedef _AlpBundleRefAlpBundleRef
 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.

Operations on Bundles

#define ALP_BUNDLE_RW_SAVED   "/saved/"
 One R/W sub-folder is automatically backed up to the desktop.
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.
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.
alp_status_t alp_bundle_delete (AlpBundle bundle, int everything)
 Delete a bundle.
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.
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.
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.
GHashTable * alp_bundle_properties (AlpBundle index, const char *property, int which)
GList * alp_bundle_all_properties (AlpBundle index)
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.
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.
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.

Operations on BundleRefs

#define ALP_BUNDLE_BAR_MANIFEST   "/Manifest.xml"
 Use this define as the path to retrieve the manifest from a bar bundle.
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.
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.
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.
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.
GIOChannel * alp_bundle_ref_ro_channel (AlpBundleRef ref, const char *path)
 Open a GIOChannel to retrieve a read-only file from a bundle.
gchar * alp_bundle_ref_ro_pathname (AlpBundleRef ref, const char *path)
 Retrieve a pathname for read-only file in 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_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_VERSION   1
#define ALP_BUNDLE_ENTRYPOINT_CLOSURE_REF(closure)   (((AlpBundleEntrypointClosure*)(closure))->ref)
 Retrieve the AlpBundleRef 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_CALLBACK(closure)   (((AlpBundleEntrypointClosure*)(closure))->callback)
 Retrieve the dlsym() function pointer 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_SYM(closure)   (((AlpBundleEntrypointClosure*)(closure))->sym)
 Retrieve the symbol name used by dlsym(), 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.
GClosure * alp_bundle_acquire_entrypoint (const char *url, AlpBundleRef relativeRef)
 Get a function pointer to a shared library 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.
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_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_execve (GClosure *closure, char *const argv[], char *const envp[])
 Invoke a GClosure with command-line parameters from an array, return result.
int alp_bundle_entrypoint_closure_execl (GClosure *closure, const char *arg,...)

Notifications

#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_COPY   "/alp/bundlemgr/copy_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_REGISTER   "/alp/bundlemgr/register_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_UNREGISTER   "/alp/bundlemgr/unregister_bundle"
#define ALP_NOTIFY_EVENT_BUNDLE_RESET_EVERYTHING   "/alp/bundlemgr/reset_everything"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_ADDED   "/alp/bundlemgr/name_added"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_REMOVED   "/alp/bundlemgr/name_removed"
#define ALP_NOTIFY_EVENT_BUNDLE_NAME_CHANGED   "/alp/bundlemgr/name_changed"
typedef _AlpNotifyEventBundleDelete AlpNotifyEventBundleDelete
typedef _AlpNotifyEventBundleMove AlpNotifyEventBundleMove
typedef _AlpNotifyEventBundleCopy AlpNotifyEventBundleCopy
typedef _AlpNotifyEventBundleRegister AlpNotifyEventBundleRegister
typedef _AlpNotifyEventBundleUnregister AlpNotifyEventBundleUnregister
typedef _AlpNotifyEventBundleResetEverything AlpNotifyEventBundleResetEverything
typedef _AlpNotifyEventBundleNameAdded AlpNotifyEventBundleNameAdded
typedef _AlpNotifyEventBundleNameRemoved AlpNotifyEventBundleNameRemoved
typedef _AlpNotifyEventBundleNameChanged AlpNotifyEventBundleNameChanged

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.

Bundle Types

These constants define the schemes for various bundle types.

#define ALP_BUNDLE_TYPE_BAR   "bar"
 The native ALP bundle type, "bar".

Miscellaneous and localization assistance

#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_acquire_glade_xml(url, root)
#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)) \
#define alp_bundle_gettext(text)   dgettext(alp_bundle_ref_gettextdomain(alp_bundle_ref_me()), (text))
const char * alp_bundle_ref_gettextdomain (AlpBundleRef ref)
const char * alp_bundle_ref_name (AlpBundleRef ref)
gchar * alp_bundle_name (AlpBundle index)
gchar * alp_bundle_saved_settings (AlpBundle index, const char *key)
gchar * alp_bundle_unsaved_settings (AlpBundle index, const char *key)
alp_status_t alp_bundle_error (void)

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 }
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.
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.
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.).

Initialization

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.
alp_status_t alp_bundle_fini (void)
 Shutdown (finalize) the bundle manager client library.

Finding bundles

AlpBundle alp_bundle_by_name (const char *name)
 Get bundle index for a given name.
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.
GList * alp_bundle_list_schemes (void)
 All of these return a GList of allocated strings.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.
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.

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.

Scheme routines

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.
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.
gchar * alp_bundle_scheme_identify (const char *filename, const char *mimetype)
 Given a filename and/or mimetype, determine what bundle scheme is appropriate.


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_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_TYPE_BAR   "bar"
 

The native ALP bundle type, "bar".

#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_UNREGISTER   "/alp/bundlemgr/unregister_bundle"
 

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

#define ALP_STATUS_BUNDLEMGR_FAILURE   (ALP_CLASS_BUNDLEMGR | 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 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 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  ) 
 

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.

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   ) 
 

All of these return a GList of allocated strings.Return a list of all valid bundle types the system supports.

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
 

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_ref_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_ref_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 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", or "ghost". 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 obtain the results, use the g_array routines:
                int i;
                for (i=0;i > results->len;i++) {
                    alp_bundle_open(g_array_index(results, AlpBundle, i));
                }
to free, use g_array_free(results);

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 Sat Dec 16 20:29:48 2006 for hiker-0.9 by  doxygen 1.4.4