share.h File Reference

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

#include "share_hash.h"

Go to the source code of this file.

Classes
struct	file_share
Defines
#define	LIBGIFTPROTO_EXPORT   /* nothing */
#define	SHARE_BACKCOMPAT
#define	SHARE_DATA(share)   (share)
Typedefs
typedef file_share	Share
typedef file_share	FileShare
Functions
EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT BOOL	share_init (Share *share, const char *path)
LIBGIFTPROTO_EXPORT void	share_finish (Share *share)
LIBGIFTPROTO_EXPORT Share *	share_new (const char *path)
LIBGIFTPROTO_EXPORT Share *	share_new_ex (struct protocol *p, const char *root, size_t root_len, const char *path, const char *mime, off_t size, time_t mtime)
LIBGIFTPROTO_EXPORT void	share_free (Share *share)
LIBGIFTPROTO_EXPORT unsigned int	share_ref (Share *share)
LIBGIFTPROTO_EXPORT unsigned int	share_unref (Share *share)
LIBGIFTPROTO_EXPORT char *	share_get_hpath (Share *share)
LIBGIFTPROTO_EXPORT void	share_set_path (Share *share, const char *path)
LIBGIFTPROTO_EXPORT void	share_set_root (Share *share, const char *root, size_t len)
LIBGIFTPROTO_EXPORT void	share_set_mime (Share *share, const char *mime)
LIBGIFTPROTO_EXPORT void	share_set_meta (Share *share, const char *key, const char *value)
LIBGIFTPROTO_EXPORT char *	share_get_meta (Share *share, const char *key)
LIBGIFTPROTO_EXPORT void	share_clear_meta (Share *share)
LIBGIFTPROTO_EXPORT void	share_foreach_meta (Share *share, DatasetForeachFn func, void *udata)
LIBGIFTPROTO_EXPORT void	share_set_udata (Share *share, const char *proto, void *udata)
LIBGIFTPROTO_EXPORT void *	share_get_udata (Share *share, const char *proto)
LIBGIFTPROTO_EXPORT BOOL	share_complete (Share *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 share_clear_meta (  Share *  share  )

Clear all previously set meta data entries.

LIBGIFTPROTO_EXPORT BOOL share_complete (  Share *  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 share_finish (  Share *  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 share_foreach_meta (  Share *  share, DatasetForeachFn  func, void *  udata )

Simple abstraction from the Share::meta member.

LIBGIFTPROTO_EXPORT void share_free (  Share *  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 char* share_get_hpath (  Share *  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 memory segment (NUL-terminated ASCII string) representing the hidden path.

LIBGIFTPROTO_EXPORT char* share_get_meta (  Share *  share, const char *  key )

Access previously set meta data.

LIBGIFTPROTO_EXPORT void* share_get_udata (  Share *  share, const char *  proto )

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

EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT BOOL share_init (  Share *  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 Share* 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 Share* share_new_ex (  struct 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 share_ref (  Share *  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 void share_set_meta (  Share *  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  value  If NULL, removes the meta data at the key supplied.

LIBGIFTPROTO_EXPORT void share_set_mime (  Share *  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.

LIBGIFTPROTO_EXPORT void share_set_path (  Share *  share, const char *  path )

Set the share objects path. This is called by share_new, which also further documents the functionality of this function.

LIBGIFTPROTO_EXPORT void share_set_root (  Share *  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.

LIBGIFTPROTO_EXPORT void share_set_udata (  Share *  share, const char *  proto, void *  udata )

Attach arbitrary user-data for your plugin using the key described by `proto'. Parameters: share  proto  Complete protocol name, as Protocol::name would recognize. udata  Arbitrary user-data to attach. If NULL, the attach user data will be removed.

LIBGIFTPROTO_EXPORT unsigned int share_unref (  Share *  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.

---