gi_share.h File Reference

Interface for referencing complex elements of a shared file. More...

#include "gi_share_hash.h"

Go to the source code of this file.

Classes
struct	gi_file_share
Defines
#define	LIBGIFTPROTO_EXPORT   /* nothing */
Typedefs
typedef gi_file_share	GiShare
Functions
EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT bool	gi_share_init (GiShare *share, const char *path)
LIBGIFTPROTO_EXPORT void	gi_share_finish (GiShare *share)
LIBGIFTPROTO_EXPORT GiShare *	gi_share_new (const char *path)
LIBGIFTPROTO_EXPORT GiShare *	gi_share_newex (struct gi_protocol *p, const char *root, size_t root_len, const char *path, const char *mime, off_t size, time_t mtime)
LIBGIFTPROTO_EXPORT void	gi_share_free (GiShare *share)
LIBGIFTPROTO_EXPORT unsigned int	gi_share_ref (GiShare *share)
LIBGIFTPROTO_EXPORT unsigned int	gi_share_unref (GiShare *share)
LIBGIFTPROTO_EXPORT GiPath *	gi_share_get_hpath (GiShare *share)
LIBGIFTPROTO_EXPORT GiPath *	gi_share_set_path (GiShare *share, const char *path)
LIBGIFTPROTO_EXPORT GiPath *	gi_share_set_root (GiShare *share, const char *root, size_t len)
LIBGIFTPROTO_EXPORT char *	gi_share_set_mime (GiShare *share, const char *mime)
LIBGIFTPROTO_EXPORT bool	gi_share_set_meta (GiShare *share, const char *key, const char *value)
LIBGIFTPROTO_EXPORT char *	gi_share_get_meta (GiShare *share, const char *key)
LIBGIFTPROTO_EXPORT void	gi_share_clear_meta (GiShare *share)
LIBGIFTPROTO_EXPORT void	gi_share_foreach_meta (GiShare *share, GiDatasetForeachFn func, void *udata)
LIBGIFTPROTO_EXPORT void *	gi_share_set_udata (GiShare *share, const char *proto, void *udata)
LIBGIFTPROTO_EXPORT void *	gi_share_get_udata (GiShare *share, const char *proto)
LIBGIFTPROTO_EXPORT bool	gi_share_complete (GiShare *share)

---

Detailed Description

Interface for referencing complex elements of a shared file.

Please note that is an integral part of the giFT communication API for protocol plugins. You are encouraged to use this internally wherever appropriate.

Also note that there is a supplementary share_hash.[ch] that provides the rest of the API. Eventually it will merged in here, but as of now it is better left independent.

---

Function Documentation

LIBGIFTPROTO_EXPORT void gi_share_clear_meta (  GiShare *  share  )

Clear all previously set meta data entries.

LIBGIFTPROTO_EXPORT bool gi_share_complete (  GiShare *  share  )

Determines if the supplied share object is filled. The current determination is that a path must be set, and that it must begin with a leading '/'.

LIBGIFTPROTO_EXPORT void gi_share_finish (  GiShare *  share  )

Corresponding to ::share_init, but will destroy any internally owned memory from the storage location provided. The calling argument will not be free'd.

LIBGIFTPROTO_EXPORT void gi_share_foreach_meta (  GiShare *  share, GiDatasetForeachFn  func, void *  udata )

Simple abstraction from the Share::meta member.

LIBGIFTPROTO_EXPORT void gi_share_free (  GiShare *  share  )

Destroy an allocated Share object and all its internally managed members as with ::share_init. The only difference between the two is that this function will free the calling argument.

LIBGIFTPROTO_EXPORT GiPath* gi_share_get_hpath (  GiShare *  share  )

Access the "hidden" path from the object that is to be sent out to remote peers when responding to searches (whichever method is used to do this by the protocol plugin). When requests come back for a new upload, they will be required to be in this form. Please note that this routine will not function properly without a path and a root value set. See ::share_set_path, and ::share_set_root for more details. Returns: A pointer to an internally managed path object. This object is directly assigned to the share object, and will be automatically freed when the share is destroyed.

LIBGIFTPROTO_EXPORT char* gi_share_get_meta (  GiShare *  share, const char *  key )

Access previously set meta data.

LIBGIFTPROTO_EXPORT void* gi_share_get_udata (  GiShare *  share, const char *  proto )

Access previously attached user-data. This should be pretty self-explanatory.

EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT bool gi_share_init (  GiShare *  share, const char *  path )

Similar to the ::share_new constructor, except that new memory is not allocated. Instead, a pre-allocated storage address is supplied.

LIBGIFTPROTO_EXPORT GiShare* gi_share_new (  const char *  path  )

Construct a new shared file object. This is intended to be used both by giFT for each local file shared as well as by protocol plugins. The protocol communication API may require usage of this structure. Parameters: path  Full local path in UNIX form. The location provided will be copied into the Share object.

LIBGIFTPROTO_EXPORT GiShare* gi_share_newex (  struct gi_protocol *  p, const char *  root, size_t  root_len, const char *  path, const char *  mime, off_t  size, time_t  mtime )

Backwards compatible interface that matches the old ::share_new. This is done as a convenience to current protocol plugins out there and will hopefully be phased out with time.

LIBGIFTPROTO_EXPORT unsigned int gi_share_ref (  GiShare *  share  )

Increment the mortality/reference count for the supplied object. Please note that the initial reference count is 1 when constructed, and will be free'd automatically using ::share_free when the reference reaches 0 from ::share_unref. Returns: The reference post-incrementation.

LIBGIFTPROTO_EXPORT bool gi_share_set_meta (  GiShare *  share, const char *  key, const char *  value )

Set arbitrary meta data. Please note that key will be copied and lowercased. A copy of value will also be made by the dataset and internally managed. Parameters: share  key  Meta data key. Duplicate keys are not currently supported. value  Data value associated with `key'. If NULL, removes the meta data at `key'. Returns: Boolean success or failure.

LIBGIFTPROTO_EXPORT char* gi_share_set_mime (  GiShare *  share, const char *  mime )

Attempts to map the supplied MIME type in an internally managed table of MIME types and then assigns a pointer there. If the MIME type has been seen before, the memory address will be shared. Returns: For convenience, Share::mime is returned after assignment.

LIBGIFTPROTO_EXPORT GiPath* gi_share_set_path (  GiShare *  share, const char *  path )

Set the share objects path. This is called by ::share_new, which also further documents the functionality of this function. Returns: For convenience, Share::path is returned after assignment.

LIBGIFTPROTO_EXPORT GiPath* gi_share_set_root (  GiShare *  share, const char *  root, size_t  len )

Copy len number of bytes of the supplied `root' parameter into an internally allocated memory segment. Special precuation is taken to avoid setting share->root to NULL even when invalid or ambiguous parameters are given here. Returns: For convenience, Share::root is returned after assignment.

LIBGIFTPROTO_EXPORT void* gi_share_set_udata (  GiShare *  share, const char *  proto, void *  udata )

Attach arbitrary user-data for your plugin using the key described by `proto'. Parameters: share  proto  Formal protocol name. This must match the protocol which is set in the GiProtocol::name field. udata  Arbitrary user-data to attach. If NULL, the attached user data will be removed. Returns: For convenience, `udata' is returned on success; otherwise, NULL.

LIBGIFTPROTO_EXPORT unsigned int gi_share_unref (  GiShare *  share  )

Decrement the mortality/reference count for the supplied object. See ::share_ref for more information. Please note that direct calls to ::share_free will not obey reference counting, only this function will. Returns: The reference post-decrementation.

---