protocol Struct Reference

#include <protocol.h>

List of all members.

Public Attributes
Public
Public members.
char *	name
char *	version_str
void *	udata
Private
Private members.
void *	handle
Dataset *	hashes
Dataset *	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 protocol *p)
int(*	trace )(struct protocol *p, char *file, int line, char *func, char *fmt,...)
int(*	tracesock )(struct protocol *p, TCPC *c, char *file, int line, char *func, char *fmt,...)
int(*	dbg )(struct protocol *p, char *fmt,...)
int(*	dbgsock )(struct protocol *p, TCPC *c, char *fmt,...)
int(*	warn )(struct protocol *p, char *fmt,...)
int(*	err )(struct protocol *p, char *fmt,...)
BOOL(*	hash_handler )(struct protocol *p, const char *type, int opt, HashFn algofn, HashDspFn dspfn)
void(*	support )(struct protocol *p, const char *feature, BOOL spt)
file_share *(*	share_lookup )(struct protocol *p, int command,...)
int(*	upload_auth )(struct protocol *p, const char *user, struct file_share *share, upload_auth_t *auth_info)
transfer *(*	upload_start )(struct protocol *p, struct chunk **chunk, const char *user, struct file_share *share, off_t start, off_t stop)
void(*	chunk_write )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, unsigned char *data, size_t len)
void(*	source_abort )(struct protocol *p, struct transfer *transfer, struct source *source)
void(*	source_status )(struct protocol *p, struct source *source, enum source_status klass, const char *disptxt)
void(*	search_result )(struct protocol *p, struct if_event *event, char *user, char *node, char *href, unsigned int avail, struct file_share *file)
void(*	search_complete )(struct protocol *p, struct if_event *event)
void(*	message )(struct protocol *p, char *message)
Protocol-specified Communication
These methods will be defined by your protocol at the time of Protocol::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 protocol *p)
void(*	destroy )(struct protocol *p)
BOOL(*	download_start )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
void(*	download_stop )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, int complete)
void(*	upload_stop )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
void(*	upload_avail )(struct protocol *p, unsigned long avail)
BOOL(*	chunk_suspend )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
BOOL(*	chunk_resume )(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)
BOOL(*	source_add )(struct protocol *p, struct transfer *transfer, struct source *source)
void(*	source_remove )(struct protocol *p, struct transfer *transfer, struct source *source)
BOOL(*	search )(struct protocol *p, struct if_event *event, char *query, char *exclude, char *realm, Dataset *meta)
BOOL(*	browse )(struct protocol *p, struct if_event *event, char *user, char *node)
BOOL(*	locate )(struct protocol *p, struct if_event *event, char *htype, char *hash)
void(*	search_cancel )(struct protocol *p, struct if_event *event)
void *(*	share_new )(struct protocol *p, struct file_share *file)
void(*	share_free )(struct protocol *p, struct file_share *file, void *data)
BOOL(*	share_add )(struct protocol *p, struct file_share *file, void *data)
BOOL(*	share_remove )(struct protocol *p, struct file_share *file, void *data)
void(*	share_sync )(struct protocol *p, int begin)
void(*	share_hide )(struct protocol *p)
void(*	share_show )(struct protocol *p)
int(*	stats )(struct protocol *p, unsigned long *users, unsigned long *files, double *size, Dataset **extra)
Optional Protocol 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 protocol *p, struct source *a, struct source *b)
int(*	user_cmp )(struct protocol *p, const char *a, const char *b)

---

Detailed Description

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

---

Member Data Documentation

BOOL(* protocol::browse)(struct protocol *p, struct if_event *event, char *user, 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(* protocol::chunk_resume)(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source)

Resume a suspended transfer. See Protocol::chunk_suspend.

BOOL(* protocol::chunk_suspend)(struct 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). Protocols 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(* protocol::chunk_write)(struct 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(* protocol::dbg)(struct protocol *p, char *fmt,...)

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

int(* protocol::dbgsock)(struct protocol *p, TCPC *c, char *fmt,...)

See Protocol::dbg and Protocol::tracesock.

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

Cleanup everything you have initialized/allocated. This will generally mean that your protocol is being unloaded either by a giFT shutdown or by a simple unload directive to this specific protocol.

BOOL(* protocol::download_start)(struct 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(* protocol::download_stop)(struct protocol *p, struct transfer *transfer, struct chunk *chunk, struct source *source, int complete)

Cancel an active download. Protocols 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(* protocol::err)(struct protocol *p, char *fmt,...)

Logging facility using the error log channel.

Dataset* protocol::features

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

void* protocol::handle

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

BOOL(* protocol::hash_handler)(struct protocol *p, const char *type, int opt, HashFn algofn, HashDspFn dspfn)

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

Dataset* protocol::hashes

alternate index of hashes on a per-protocol basis

BOOL(* protocol::init)(struct protocol *p)

Initialization function. This should not actually "start" the protocol, merely setup the Protocol 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  Protocol 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(* protocol::locate)(struct protocol *p, struct if_event *event, char *htype, char *hash)

Locate a file on the network by some unique content. See Protocol::browse and Protocol::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.

void(* protocol::message)(struct protocol *p, char *message)

Deliver a raw message to the interface protocol. Parameters: p  message  persist  If true, this message will be delivered each time a user attaches to the running daemon.

char* protocol::name

protocol name

BOOL(* protocol::search)(struct protocol *p, struct if_event *event, char *query, char *exclude, char *realm, Dataset *meta)

Search request. Please note that Protocol::browse and Protocol::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(* protocol::search_cancel)(struct protocol *p, struct if_event *event)

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

void(* protocol::search_complete)(struct protocol *p, struct if_event *event)

Inform giFT that all search results that can be delivered have been delivered, or there is some reasonable reason 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(* protocol::search_result)(struct protocol *p, struct if_event *event, char *user, char *node, char *href, unsigned int avail, struct 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  Protocol-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 Protocol::support. file  Complete FileShare structure. See Protocol::share_new.

BOOL(* protocol::share_add)(struct protocol *p, struct file_share *file, void *data)

Add a new locally shared file to the network. Parameters: p  file  data  Arbitrary data returned from Protocol::share_new. Returns: Boolean success or failure.

void(* protocol::share_free)(struct protocol *p, struct file_share *file, void *data)

Destroy data returned by Protocol::share_new.

void(* protocol::share_hide)(struct 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 file_share*(* protocol::share_lookup)(struct 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*(* protocol::share_new)(struct protocol *p, struct file_share *file)

Allocate new protocol-specific data to be associated with file. Returns: Pointer to protocol-specific dynamically allocated memory.

BOOL(* protocol::share_remove)(struct protocol *p, struct file_share *file, void *data)

Remove a locally shared file from the network. See Protocol::share_add.

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

Enable sharing after it was previously hidden.

void(* protocol::share_sync)(struct protocol *p, int begin)

giFT has begun syncing shares. Expect Protocol::share_add and Protocol::share_remove calls until begin is FALSE, in which case the sync has completed. This is to be considered an effective modification of the current local shares and should be sent out over the socket if said protocol requires this. Parameters: p  begin

void(* protocol::source_abort)(struct 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(* protocol::source_add)(struct 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(* protocol::source_cmp)(struct 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(* protocol::source_remove)(struct 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(* protocol::source_status)(struct 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(* protocol::start)(struct protocol *p)

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

int(* protocol::stats)(struct protocol *p, unsigned long *users, unsigned long *files, double *size, Dataset **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(* protocol::support)(struct 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 Protocol::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(* protocol::trace)(struct protocol *p, char *file, int line, char *func, char *fmt,...)

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

int(* protocol::tracesock)(struct protocol *p, TCPC *c, char *file, int line, char *func, char *fmt,...)

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* protocol::udata

arbitrary data associated by the plugin

int(* protocol::upload_auth)(struct protocol *p, const char *user, struct 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 Protocol::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 Protocol::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 Protocol::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(* protocol::upload_avail)(struct protocol *p, unsigned long avail)

Notify the protocol of upload availability changes. Protocols 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*(* protocol::upload_start)(struct protocol *p, struct chunk **chunk, const char *user, struct 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 Protocol::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 Protocol::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 Protocol::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 Protocol::chunk_write. You may at any time receive a Protocol::upload_stop call that will request you clean up any data you associate after the transfer has begun.

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

See Protocol::download_stop.

int(* protocol::user_cmp)(struct 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* protocol::version_str

protocol version, will be shown by giFT -V

int(* protocol::warn)(struct protocol *p, char *fmt,...)

Logging facility using the warning log channel.

---

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

• protocol.h

---