ezFCPlib An easy to use API for Freenet C/C++ Clients Reference Manual by Jay Oliveri ----------------------------------------------------------------------- Contents ----------------------------------------------------------------------- Anything postfixed with (n/a) means that function is currently not available (because it's simply not implemented yet). *) Introduction *) Required Header Files - ezfcplib.h *) C-Struct Functions - fcpCreateHFCP - fcpInheritHFCP - fcpDestroyHFCP - fcpCreateHURI - fcpDestroyHURI - fcpParseURI *) Establishment Functions - fcpStartup - fcpTerminate *) Key Functions - fcpMakeSvkKeypair - fcpMakeChkFromFile(n/a) *) High Level Freenet Functions - fcpPutKeyFromFile - fcpGetKeyToFile(n/a) *) Low Level Freenet Functions - fcpOpenKey - fcpReadKey(n/a) - fcpWriteKey - fcpReadMetadata(n/a) - fcpWriteMetadata - fcpCloseKey *) Protocol Functions - fcpClientHello - fcpClientInfo(n/a) ----------------------------------------------------------------------- * Introduction ------------------------------------------------------------------------ Words words words words words words words words words words words words words ------------------------------------------------------------------------ * Required Header Files ------------------------------------------------------------------------ The file "ezfcplib.h" contains function prototypes and #define'd constants available to the user of ezFCPlib. This file also defines every C style structure used throughout the library. Any functions or struct memebers *not* documented here should *not* be used. It should be considered part of the implementation and subject to change without notice. ------------------------------------------------------------------------ * C-Struct Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + hURI *fcpCreateHFCP(void) Brief: Creates a new and empty hFCP handle. Arguments: None Return Value: Pointer to new hFCP handle; 0 on error. Description Creates a new and empty hFCP handle. All the values within are filled in with defaults that are defined in ezfcplib.h (EZFCP_DEFAULT_*). + hFCP *fcpInheritHFCP(hFCP *hfcp) Brief: Creates a new hFCP handle with the same values as argument's. Arguments: hfcp: FCP handle to duplicate. Return Value: Pointer to a duplicate of argument hFCP handle. Description Creates a new hFCP handle with the same values as argument's. Useful when writing sub-procedures that should essentially use the same parameters as the "parent" FCP connection. + void fcpDestroyHFCP(hFCP *hfcp) Brief: Destroys hFCP handle and all (un)documented nested struct members. Arguments: hfcp: FCP handle to free. Return Value: None. Description Destroys hFCP handle and all nested structs within by calling each respective struct's _fcpDestroy*() function. Further information in the source file fcpCreation.c. Example using fcpCreateHFCP(), fcpInheritHFCP(), fcpDestroyHFCP(): + hURI *fcpCreateHURI(void) Brief: Creates a new and empty hURI handle. Arguments: None Return Value: Pointer to an allocated hURI handle; 0 on error. Description Creates a new and empty hURI handle. All the values within are filled in with defaults that are defined in ezfcplib.h (EZFCP_DEFAULT_*). + void fcpDestroyHURI(hFCP *hfcp) Brief: Destroys hURI handle. Arguments: hfcp: Allocated hFCP handle to free. Return Value: None. Description Destroys hURI handle and all nested structs within. + int *fcpParseURI(hURI *uri, char *key) Brief: Create a new hURI handle and set it to the key argument. Arguments: uri: Must be an allocated hURI handle. key: String containing Freenet key to parse into handle. Return Value: 0 on success, negative number on error. Description Parses a C-syle string into an hURI handle. If the key cannot be parsed properly, function returns a negative error code. Example using fcpCreateHURI(), fcpDestroyHURI(), fcpParseURI(): ------------------------------------------------------------------------ * Establishment Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + int fcpStartup(char *logfile, int retry, int log_verbosity) Brief: Perform ezFCPlib intialization. Arguments: logfile: C string containing filename to write log to (0 to send output to standard out. retry: Retry count on socket timeouts for FCP connections. log_verbosity: Level of log verbosity. Possible values: FCP_LOG_SILENT FCP_LOG_CRITICAL FCP_LOG_NORMAL FCP_LOG_VERBOSE FCP_LOG_DEBUG Return Value: 0 on success, negative number on error. Description This function performs initial steps before general ezFCPlib usage can take place. On Windows, the Winsock subsystem is also intialized. + void fcpTerminate(void) Brief: Perform ezFCPlib termination. Arguments: None. Return Value: None. Example using fcpStartup(), fcpTerminate(): ------------------------------------------------------------------------ * Key Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + int fcpMakeSvkKeypair(hFCP *hfcp, char *pub_key, char *priv_key, char *entropy) Brief: Arguments: hfcp: hFCP handle. Return Value: 0 on success, negative number on error. Description Example using fcpMakeSvkKeypair(): ------------------------------------------------------------------------ * High Level Freenet Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + int fcpPutKeyFromFile(hFCP *hfcp, char *key_uri, char *key_filename, char *meta_filename) Brief: Insert data from a local file into Freenet. Arguments: hfcp: hFCP handle. key_uri: C string containing freenet key. May be 1 of the following formats: CHK@ KSK@ SSK@[/] key_filename: Local filename of freenet data to insert. meta_filename: Local filename of metadata to insert with key data. Return Value: 0 on success, negative number on error. Description This function will insert a local file key_filename into freenet. The file can be inserted as a normal CHK@ or an FEC encoded redundant splitfile, depending on the size of the file. + int fcpGetKeyToFile(hFCP *hfcp, char *key_uri, char *key_filename, char *meta_filename) (n/a) Brief: Arguments: Return Value: 0 on success, negative number on error. Description Example using fcpPutKeyFromFile(), fcpGetKeyFromFile(): ------------------------------------------------------------------------ * Low Level Freenet Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + int fcpOpenKey(hFCP *hfcp, char *key, int mode) Brief: Arguments: Return Value: 0 on success, negative number on error. Description + int fcpWriteKey(hFCP *hfcp, char *buf, int len) Brief: Arguments: Return Value: 0 on success, negative number on error. Description + int fcpReadKey(hFCP *hfcp, char *buf, int len) (n/a) Brief: Arguments: Return Value: 0 on success, negative number on error. Description + int fcpWriteMetadata(hFCP *hfcp, char *buf, int len) Brief: Arguments: Return Value: 0 on success, negative number on error. Description + int fcpReadMetadata(hFCP *hfcp, char *buf, int len) (n/a) Brief: Arguments: Return Value: 0 on success, negative number on error. Description + int fcpCloseKey(hFCP *hfcp) Brief: Arguments: Return Value: 0 on success, negative number on error. Description Example using fcpOpenKey(), fcpWriteKey(), fcpReadKey(), fcpWriteMetadata(), fcpReadMetadata(), fcpCloseKey(): ------------------------------------------------------------------------ * Protocol Functions ------------------------------------------------------------------------ Words words words words words words words words words words words words words + int fcpClientHello(hFCP *hfcp); Brief: Arguments: hfcp: hFCP handle. Return Value: 0 on success, negative number on error. Description + int fcpClientInfo(hFCP *hfcp); Brief: Arguments: hfcp: hFCP handle. Return Value: 0 on success, negative number on error. Description Example using fcpClientHello(), fcpClientInfo():