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

acquisition.c File Reference

#include <hiker/bundlemgr.h>
#include <hiker/prv/bundlemgr_prv.h>
#include <hiker/fail.h>
#include <hiker/ipc.h>
#include <string.h>
#include <stdlib.h>
#include <sqlite3.h>
#include <unistd.h>
#include <stdarg.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <dirent.h>
#include <dlfcn.h>
#include <signal.h>
#include <errno.h>
#include <sys/wait.h>
#include "pm_traces.h"
#include "pm_globals.h"
#include "pm_ipc.h"
#include "pm_sql.h"

Functions

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.
GClosure * alp_bundle_acquire_entrypoint (const char *url, AlpBundleRef relativeRef)
 Get a function pointer to a shared library 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,...)


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);

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


Generated on Sat Dec 16 20:29:48 2006 for hiker-0.9 by  doxygen 1.4.4