gi_protocol Struct Reference

#include <gi_protocol.h>

List of all members.

Public Attributes
Public
Public members.
char *	name
char *	version
void *	udata
Private
Private members.
bool	active
void *	handle
GiDataset *	hashes
GiDataset *	features
giFT Assigned Methods
Communication methods defined by giFT before protocol's initialization. No protocol should override these, however, most protocols will want to call at least some of these throughout the course of their protocol's lifespan.
bool(*	init )(struct gi_protocol *p)
int(*	trace )(struct gi_protocol *p, const char *file, unsigned int line, const char *funcname, int level, const char *fmt,...) GI_PRINTF_ATTR(6
int(*	tracesock )(struct gi_protocol *p, GiTcp *conn, const char *file, unsigned int line, const char *funcname, int level, const char *fmt,...) GI_PRINTF_ATTR(7
int(*	dbg )(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3
int(*	dbgsock )(struct gi_protocol *p, GiTcp *conn, int level, const char *fmt,...) GI_PRINTF_ATTR(4
int(*	warn )(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3
int(*	err )(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3
bool(*	hash_handler )(struct gi_protocol *p, struct gi_hash_handler *handler)
void(*	support )(struct gi_protocol *p, const char *feature, bool spt)
gi_file_share *(*	share_lookup )(struct gi_protocol *p, int command,...)
int(*	upload_auth )(struct gi_protocol *p, const char *user, struct gi_file_share *share, upload_auth_t *auth_info)
transfer *(*	upload_start )(struct gi_protocol *p, struct chunk **chunk, const char *user, struct gi_file_share *share, off_t start, off_t stop)
void(*	chunk_write )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, unsigned char *data, size_t len)
void(*	source_abort )(struct gi_protocol *p, struct transfer *transfer, struct source *source)
void(*	source_status )(struct gi_protocol *p, struct source *source, enum source_status klass, const char *disptxt)
void(*	search_result )(struct gi_protocol *p, void *event, const char *user, const char *node, const char *href, unsigned int avail, struct gi_file_share *file)
void(*	search_complete )(struct gi_protocol *p, void *event)
GiProtocol-specified Communication
These methods will be defined by your protocol at the time of GiProtocol::init. You should understand that you do not need to initialize all these values, as giFT will provide dummy implementations for them as to guarantee no method points to NULL. However, you should note that a failure to set certain key communication methods will result in a nearly worthless protocol plugin.
bool(*	start )(struct gi_protocol *p)
void(*	stop )(struct gi_protocol *p)
void(*	destroy )(struct gi_protocol *p)
bool(*	download_start )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
void(*	download_stop )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, int complete)
void(*	upload_stop )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
void(*	upload_avail )(struct gi_protocol *p, unsigned long avail)
bool(*	chunk_suspend )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
bool(*	chunk_resume )(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
bool(*	source_add )(struct gi_protocol *p, struct transfer *transfer, struct source *source)
void(*	source_remove )(struct gi_protocol *p, struct transfer *transfer, struct source *source)
bool(*	search )(struct gi_protocol *p, const void *event, const char *query, const char *exclude, const char *realm, GiDataset *meta)
bool(*	browse )(struct gi_protocol *p, const void *event, const char *user, const char *node)
bool(*	locate )(struct gi_protocol *p, const void *event, const char *htype, const char *hash)
void(*	search_cancel )(struct gi_protocol *p, void *event)
void(*	share_sync_begin )(struct gi_protocol *p)
void(*	share_sync_end )(struct gi_protocol *p)
void(*	share_add )(struct gi_protocol *p, struct gi_file_share *file)
void(*	share_remove )(struct gi_protocol *p, struct gi_file_share *file)
void(*	share_hide )(struct gi_protocol *p)
void(*	share_show )(struct gi_protocol *p)
int(*	stats )(struct gi_protocol *p, unsigned long *users, unsigned long *files, double *size, GiDataset **extra)
Optional GiProtocol Communication
Methods which can (and probably should) be specified by each protocol, but will have sane and useful default implementations specified by giFT. Your protocol will not be adversely affected if you leave these values as is.
int(*	source_cmp )(struct gi_protocol *p, struct source *a, struct source *b)
int(*	user_cmp )(struct gi_protocol *p, const char *a, const char *b)

---

Detailed Description

GiProtocol structure containing methods for bidirectional communication between daemon and protocol plugin.

---

Member Data Documentation

bool gi_protocol::active

For all time between a call to p->start and p->stop, active will be true; otherwise, false

bool(* gi_protocol::browse)(struct gi_protocol *p, const void *event, const char *user, const char *node)

Browse an individual users content. The response to this event uses the same systems as a search. Parameters: p  event  user  User to browse. You should expect this in the form you return from search results. node  Node/server that reported this users shares, if available. If possible, do not rely on this value as it is only provided for search results.

bool(* gi_protocol::chunk_resume)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)

Resume a suspended transfer. See GiProtocol::chunk_suspend.

bool(* gi_protocol::chunk_suspend)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)

Suspend input/output on the specified chunk until resumed later. giFT uses these methods for managing transfer bandwidth usage (user-space throttling). GiProtocols should do their best to implement this. Parameters: p  transfer  chunk  source  Returns: Boolean success or failure. Return false if your protocol does not support this feature.

void(* gi_protocol::chunk_write)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, unsigned char *data, size_t len)

Write data to the specified bidirectional chunk object. This is used for transfers when data has either been completely received or sent out (not considering kernel-level socket buffering). giFT will internally track transfer progress and/or write the necessary data to file. Parameters: p  transfer  chunk  source  data  len

int(* gi_protocol::dbg)(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3

Print debugging information to the appropriate logging channel. This data does not include information about the line that produced the log message.

int(* gi_protocol::dbgsock)(struct gi_protocol *p, GiTcp *conn, int level, const char *fmt,...) GI_PRINTF_ATTR(4

See GiProtocol::dbg and GiProtocol::tracesock.

void(* gi_protocol::destroy)(struct gi_protocol *p)

Prepare your plugin to be unloaded via the dynamic loading infrastructure. All hooks into giftd's event loop should be removed, and all memory should be freed. Note: This method will only be used on a "stopped" plugin. See GiProtocol::stop for more details.

bool(* gi_protocol::download_start)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)

Begin a new chunk transfer. Note that the protocol is not allowed to differentiate between multi-sourced and single-sourced transfers, you must simply obey what is specified by the chunk argument. Parameters: p  transfer  chunk  source  Returns: Boolean success or failure.

void(* gi_protocol::download_stop)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, int complete)

Cancel an active download. GiProtocols are expected to cleanup all sockets and internal data associated with this chunk. Please note that OpenFT violates this specification by attempting to use persisting HTTP connections for transfers. Parameters: p  transfer  chunk  source  complete  Indicates whether or not this chunk completed successfully. Do not attempt to figure this out on your own using chunk->start/stop as this flag has other considerations.

int(* gi_protocol::err)(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3

Logging facility using the error log channel.

GiDataset* gi_protocol::features

GiProtocol features Parameters: static-chunks  range-get  user-browse  hash-unique  chat-user  chat-group

void* gi_protocol::handle

lt_dlopen handle (NOTE: We can't use lt_dlhandle here because plugins depend on the size of this structure, but may not have lt_dlopen available!)

bool(* gi_protocol::hash_handler)(struct gi_protocol *p, struct gi_hash_handler *handler)

Adds a new hashing algorithm handler for this plugin. Please note that while only one primary hashing routine may be specified, multiple secondary routines are allowed. Parameters: type  String literal to represent the hashing algorithm. Common names are SHA1, MD5, etc. opt  Handler options specific to the way giFT understands what your plugin needs. Using HASH_PRIMARY will cause all local shares to be hashed, however, HASH_SECONDARY algos will still be able to verify download integrity. If the HASH_LOCAL flag is present, local shares will be hashed using the supplied secondary algorithm. algofn  Primary hashing function. dspfn  Callback handler used to create an ASCII string representation of the hash supplied. If NULL is supplied, a simple hex conversion will take place. Returns: Boolean success or failure.

GiDataset* gi_protocol::hashes

Alternate index of hashes on a per-protocol basis

bool(* gi_protocol::init)(struct gi_protocol *p)

Initialization function. This should not actually "start" the protocol, merely setup the GiProtocol structure passed. Note that giFT assigns this value before plugin initialization is called, and will always be set to your protocol's fully qualified case-sensitive name with the string literal "_init" appened to the ending. So, for OpenFT's case, this value will be set to OpenFT_init prior to the calling of said function. Parameters: p  GiProtocol pointer associated with the plugin being initialized. This object is a private communication stream between giFT and the plugin exclusively. Returns: Boolean success or failure.

bool(* gi_protocol::locate)(struct gi_protocol *p, const void *event, const char *htype, const char *hash)

Locate a file on the network by some unique content. See GiProtocol::browse and GiProtocol::search. Parameters: p  event  htype  Optional hashing algorithm name. If NULL, assume that the hashing type is whatever you registered using HASH_PRIMARY. hash  NUL-terminated ASCII string representing the hash to search for.

char* gi_protocol::name

Protocol name

bool(* gi_protocol::search)(struct gi_protocol *p, const void *event, const char *query, const char *exclude, const char *realm, GiDataset *meta)

Search request. Please note that GiProtocol::browse and GiProtocol::locate use the same result and completion routines as they are actually the same in giFT space. Parameters: p  event  Internal event used for search response. query  Query string. exclude  Exclude string. realm  Filtering by group. meta  Extended search information. Returns: If true, the search will be assumed to have succeeded pending a response from the protocol at some later time. Otherwise, the search is terminated immediately afterwards and anymore replies to this event will be considered invalid.

void(* gi_protocol::search_cancel)(struct gi_protocol *p, void *event)

Cancel a previously requested search. Parameters: p  event  Internal event delivered by the search request.

void(* gi_protocol::search_complete)(struct gi_protocol *p, void *event)

Inform giFT that all search results that can be delivered have been delivered, or it is reasonable to assume we have received the bulk of all results (if your protocol has no concept of clean search termination). This will "cancel" the search event gracefully and return to the interface protocol that your plugin has terminated.

void(* gi_protocol::search_result)(struct gi_protocol *p, void *event, const char *user, const char *node, const char *href, unsigned int avail, struct gi_file_share *file)

Send a search result from the plugin. This communication is used by the protocol when results need to be delivered to the interface protocol. Parameters: p  event  Internal event delivered by the search request. user  Arbitrary protocol-specific string attempting to uniquely represent the user which has the result. node  Parent node or server which returned the result. May be NULL. href  GiProtocol-specific reference string. Example: Napster://jasta[gnapster]/file.mp3. avail  Availability of this file. If the protocol has no concept of this, use 0. You should also inform giFT that your protocol has no support for availability through GiProtocol::support. file  Complete FileShare structure. See GiProtocol::share_new.

void(* gi_protocol::share_add)(struct gi_protocol *p, struct gi_file_share *file)

Notification that a new locally shared file is available. When the daemon first starts up, and after the plugins have been loaded (but not necessarily started with GiProtocol::start), all shares found in the ~/.giFT/shares database will be given an individual call to this function in order to register it for the first time to plugins. After that, only synchronization requests will be capable of calling upon this interface. Note: The exact semantics of this call do not imply that the file must immediately be injected into the network, or even that your plugin must have been started first. You are required only to associate any persistent user data that you will need when later accessing the Share handle given through this interface. Parameters: p  file  Share object maintained in giFT space and guaranteed to have persistent lifetime storage up until p->share_remove is delivered. Returns: Boolean success or failure.

void(* gi_protocol::share_hide)(struct gi_protocol *p)

Temporarily unshare all files. Some protocols (eg OpenFT) implement this with a single command disabling shares instead of removing them. To my knowledge, most other protocols will require you actually unshare every file manually.

struct gi_file_share*(* gi_protocol::share_lookup)(struct gi_protocol *p, int command,...)

Lookup a locally shared file based on `command' criteria. This is the only interface to directly query the internally managed share cache. share = p->share_lookup (p, SHARE_LOOKUP_HASH, "MD5", md5sum, 16); I apologize for the relative lack of documentation provided for this function. Hopefully I will get around to it soon (boy do I say that a lot *grin*). Parameters: p  command  Lookup type to perform. Possible commands are defined above. ...  Command-specific lookup arguments. Returns: Direct pointer into the local share cache or NULL if the entry was not found.

void(* gi_protocol::share_remove)(struct gi_protocol *p, struct gi_file_share *file)

Notification that a previously shared object is no longer available to this plugin. This does not necessarily imply that the file has been removed by the user and is thus not available on disk, simply that your plugin is no longer allowed to share it, or associate user data. Note: This call will be given for every share in the current share index when your plugin is to be unloaded during runtime.

void(* gi_protocol::share_show)(struct gi_protocol *p)

Enable sharing after it was previously hidden.

void(* gi_protocol::share_sync_begin)(struct gi_protocol *p)

This message notifies your plugin that the daemon is preparing to make changes to the local share index. Within the window of a call to GiProtocol::share_sync_begin and GiProtocol::share_sync_end, you should be expected to process and handle GiProtocol::share_add and GiProtocol::share_remove requests. Modifications to the share index may never occur outside of the context of this notification.

void(* gi_protocol::share_sync_end)(struct gi_protocol *p)

See ::share_sync_begin.

void(* gi_protocol::source_abort)(struct gi_protocol *p, struct transfer *transfer, struct source *source)

Cancel a source as though the user had requested its removal. This is useful when your plugin knows (much better than giFT) that attempting to retrieve from this source is futile or that it could be dangerous. Please note that giFT has an internal automagic timeout for sources that do not have data throughput. Parameters: p  transfer  source

bool(* gi_protocol::source_add)(struct gi_protocol *p, struct transfer *transfer, struct source *source)

Notify a protocol about a new source being added to a transfer. This affects only downloads. Returns: Return false if giFT should abort adding this source, effectively ignoring that addsource request. Please note that at the time of this writing, a return value of false is not implemented for internal reasons. If you encounter this to still be the case, notify the developers and the feature will be finished.

int(* gi_protocol::source_cmp)(struct gi_protocol *p, struct source *a, struct source *b)

Compare two sources. This will be used when selecting how to manage multiple "similar" sources to a single transfer. The sources should compare equal (return value of 0) when it can be determined that they are the same user sharing the same file. Returns: Identical to strcmp.

void(* gi_protocol::source_remove)(struct gi_protocol *p, struct transfer *transfer, struct source *source)

Remove all activity and pending data for the specified source. This method is used when giFT has been instructed to remove a source from the specified transfer (you may assume that this is a download), or when a transfer has completed all sources will be removed.

void(* gi_protocol::source_status)(struct gi_protocol *p, struct source *source, enum source_status klass, const char *disptxt)

Set the source status. Parameters: p  source  klass  Basic status grouping so that giFT may still apply some broad logic based on transfer progress/status. disptxt  Literal text to display to the giFT clients.

bool(* gi_protocol::start)(struct gi_protocol *p)

Start the protocol connections. See GiProtocol::init for a more detailed description as to why this separation was decided upon. Returns: Boolean success or failure.

int(* gi_protocol::stats)(struct gi_protocol *p, unsigned long *users, unsigned long *files, double *size, GiDataset **extra)

Request protocol statistics. Parameters: p  users  Storage location for the number of users. files  Storage location for the number of files. size  Storage location for the total shared size (GB). extra  Extra information this protocol would like to be reported. Please use sparingly. Returns: Number of connections currently established. Any value above zero will be considered "Online".

void(* gi_protocol::stop)(struct gi_protocol *p)

Stop protocol connections and release any input/timer events. This operation is usually performed when giftd has been asked to disable the protocol plugin, but not unload it.

void(* gi_protocol::support)(struct gi_protocol *p, const char *feature, bool spt)

Add a protocol feature. This informs giFT of the various protocol/network-specific features this plugin can or can not successfully implement so as to modify giFT's behaviour. Currently, none of the feature-set defined by the default plugin (OpenFT) is actually used conditionally, however there will come a time when that is the case. For now it is probably safe just to ignore this. For a detailed list of supported options, see GiProtocol::features. Parameters: p  feature  Feature's name, this is not an arbitrary string and should be selected from a determined list that we will eventually provide. spt  Boolean value for this feature's support.

int(* gi_protocol::trace)(struct gi_protocol *p, const char *file, unsigned int line, const char *funcname, int level, const char *fmt,...) GI_PRINTF_ATTR(6

Method for producing informative log lines from within a protocol plugin. Do not use this function directly, see ::DBGFN instead.

int(* gi_protocol::tracesock)(struct gi_protocol *p, GiTcp *conn, const char *file, unsigned int line, const char *funcname, int level, const char *fmt,...) GI_PRINTF_ATTR(7

Special debugging method that will automatically format and display the peer information. This would not be provided unless I was pretty sure every plugin will use remote sockets <g>.

void* gi_protocol::udata

Arbitrary data associated by the plugin

int(* gi_protocol::upload_auth)(struct gi_protocol *p, const char *user, struct gi_file_share *share, upload_auth_t *auth_info)

Inform giFT of a new upload request, specifically one which needs access to a locally shared object (that is, something in gift:/sharing/root). The return value from this function will help determine how the plugin should proceed. Parameters: p  user  Username that can be compared with previously registered uploads. Consider setting and using GiProtocol::user_cmp for this to work well. share  Share that we are considering for upload. auth_info  Optional interface for retrieving additional information from the auth call, such as which queue position the request *has been placed in for UPLOAD_AUTH_MAX. Return values: UPLOAD_AUTH_ALLOW  Upload has been accepted. You still need to call GiProtocol::upload_start when the transfer should be displayed. Please note that you must minimize the window between an upload_request call and an upload_start call to prevent users from slipping under the queue. UPLOAD_AUTH_STALE  The share requested has changed since the last share sync. This triggers an immediate non-blocking share sync, and the transfer should be temporarily aborted. UPLOAD_AUTH_MAX  Maximum uploads currently reached. Please note that an internally managed fair upload queue is maintained and can be access using GiProtocol::upload_queue. This queue is based on the assumption that the download will be retried until allowed. You may disable this functionality through the features dataset. UPLOAD_AUTH_MAX_PERUSER  The user is already downloading a file from us, and will not be allowed to occupy two positions at once. A local queue should be implemented in whichever client made this request. UPLOAD_AUTH_NOTSHARED  The requested object is not a valid share according to the currently loaded shares database. No action is taken to resync automatically. UPLOAD_AUTH_HIDDEN  The user is not sharing any files at the moment, but may share in the future.

void(* gi_protocol::upload_avail)(struct gi_protocol *p, unsigned long avail)

Notify the protocol of upload availability changes. GiProtocols such as OpenFT take advantage of this by delivering to parent search nodes so that search results for other users can indicate the availability before download. Any protocol that has no concept of upload eligibility/availability, can safely ignore this. Parameters: p  avail  Total number of available upload positions.

struct transfer*(* gi_protocol::upload_start)(struct gi_protocol *p, struct chunk **chunk, const char *user, struct gi_file_share *share, off_t start, off_t stop)

Inform giFT of a new upload which is about to begin. Please note that this does not tackle authorization of the share and in fact allows subversion of that entire system if you so wish. For normal uploads you will definitely want to obey the auth rules so I highly suggest calling and properly handling GiProtocol::upload_request prior to using this method. Parameters: p  chunk  Storage location for the chunk handle of the newly created transfer. user  Username that will be reported to the interface protocol. share  Shared object used to specify the upload. Under normal circumstances this should be returned to you from GiProtocol::share_lookup. Please note that the hash value will be extracted based on the registered hashing algorithms of this protocol. This interface does not require that you use a share from GiProtocol::share_lookup, only that it is recommended. You may optionally provide your own protocol-defined upload by filling in the following fields: Share::path Share::mime Share::size You must also set a valid hash for the primary registered hashing algorithm for your plugin. Parameters: start  Beginning file offset that will be uploaded. stop  End offset to be delivered. Returns: Transfer handle to use with the subsequent called to GiProtocol::chunk_write. You may at any time receive a GiProtocol::upload_stop call that will request you clean up any data you associate after the transfer has begun.

void(* gi_protocol::upload_stop)(struct gi_protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)

See GiProtocol::download_stop.

int(* gi_protocol::user_cmp)(struct gi_protocol *p, const char *a, const char *b)

Compare two users. This was specially added for OpenFT so that node aliases could be weeded out as a significant portion of the username field. Default implementation here is a simple strcmp.

char* gi_protocol::version

Protocol version, will be shown by giFT -V

int(* gi_protocol::warn)(struct gi_protocol *p, int level, const char *fmt,...) GI_PRINTF_ATTR(3

Logging facility using the warning log channel.

---

The documentation for this struct was generated from the following file:

• gi_protocol.h

---