1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845 |
- /*
- This file is part of GNUnet
- Copyright (C) 2004--2013 GNUnet e.V.
- GNUnet is free software: you can redistribute it and/or modify it
- under the terms of the GNU Affero General Public License as published
- by the Free Software Foundation, either version 3 of the License,
- or (at your option) any later version.
- GNUnet is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License
- along with this program. If not, see <http://www.gnu.org/licenses/>.
- SPDX-License-Identifier: AGPL3.0-or-later
- */
- /**
- * @author Christian Grothoff
- *
- * @file
- * API for file sharing via GNUnet
- *
- * @defgroup fs FS service
- * File sharing
- *
- * @see [Documentation](https://gnunet.org/file-sharing-service)
- *
- * @{
- */
- #ifndef GNUNET_FS_LIB_H
- #define GNUNET_FS_LIB_H
- #include "gnunet_util_lib.h"
- #ifdef __cplusplus
- extern "C"
- {
- #if 0 /* keep Emacsens' auto-indent happy */
- }
- #endif
- #endif
- /**
- * Version number of the implementation.
- * History:
- *
- * 1.x.x: initial version with triple GNUNET_hash and merkle tree
- * 2.x.x: root node with mime-type, filename and version number
- * 2.1.x: combined GNUNET_EC_ContentHashKey/3HASH encoding with 25:1 super-nodes
- * 2.2.x: with directories
- * 3.0.x: with namespaces
- * 3.1.x: with namespace meta-data
- * 3.2.x: with collections
- * 4.0.x: with expiration, variable meta-data, kblocks
- * 4.1.x: with new error and configuration handling
- * 5.0.x: with location URIs
- * 6.0.0: with support for OR in KSKs
- * 6.1.x: with simplified namespace support
- * 9.0.0: CPS-style integrated API
- * 9.1.1: asynchronous directory scanning
- * 9.2.0: unified K-Block and S-block format (#2564)
- * 9.3.0: base32crockford encoded URLs
- */
- #define GNUNET_FS_VERSION 0x00090300
- /* ******************** URI API *********************** */
- #define GNUNET_FS_URI_PREFIX "gnunet://fs/"
- #define GNUNET_FS_URI_KSK_INFIX "ksk/"
- #define GNUNET_FS_URI_SKS_INFIX "sks/"
- #define GNUNET_FS_URI_CHK_INFIX "chk/"
- #define GNUNET_FS_URI_LOC_INFIX "loc/"
- /**
- * How often do we signal applications that a probe for a particular
- * search result is running? (used to visualize probes).
- */
- #define GNUNET_FS_PROBE_UPDATE_FREQUENCY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MILLISECONDS, 250)
- /**
- * A Universal Resource Identifier (URI), opaque.
- */
- struct GNUNET_FS_Uri;
- /**
- * Iterator over keywords
- *
- * @param cls closure
- * @param keyword the keyword
- * @param is_mandatory is the keyword mandatory (in a search)
- * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to abort
- */
- typedef int
- (*GNUNET_FS_KeywordIterator) (void *cls,
- const char *keyword,
- int is_mandatory);
- /**
- * Get a unique key from a URI. This is for putting URIs
- * into HashMaps. The key may change between FS implementations.
- *
- * @param uri uri to convert to a unique key
- * @param key wherer to store the unique key
- * @return #GNUNET_OK on success
- */
- int
- GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri,
- struct GNUNET_HashCode *key);
- /**
- * Convert a URI to a UTF-8 String.
- *
- * @param uri uri to convert to a string
- * @return the UTF-8 string
- */
- char *
- GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri);
- /**
- * Convert keyword URI to a human readable format
- * (i.e. the search query that was used in the first place)
- *
- * @param uri ksk uri to convert to a string
- * @return string with the keywords
- */
- char *
- GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
- /**
- * Add the given keyword to the set of keywords represented by the URI.
- * Does nothing if the keyword is already present.
- *
- * @param uri ksk uri to modify
- * @param keyword keyword to add
- * @param is_mandatory is this keyword mandatory?
- */
- void
- GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri,
- const char *keyword,
- int is_mandatory);
- /**
- * Remove the given keyword from the set of keywords represented by the URI.
- * Does nothing if the keyword is not present.
- *
- * @param uri ksk uri to modify
- * @param keyword keyword to add
- */
- void
- GNUNET_FS_uri_ksk_remove_keyword (struct GNUNET_FS_Uri *uri,
- const char *keyword);
- /**
- * Convert a UTF-8 String to a URI.
- *
- * @param uri string to parse
- * @param emsg where to store the parser error message (if any)
- * @return NULL on error
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_parse (const char *uri,
- char **emsg);
- /**
- * Free URI.
- *
- * @param uri uri to free
- */
- void
- GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
- /**
- * How many keywords are ANDed in this keyword URI?
- *
- * @param uri ksk uri to get the number of keywords from
- * @return 0 if this is not a keyword URI
- */
- unsigned int
- GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
- /**
- * Iterate over all keywords in this keyword URI.
- *
- * @param uri ksk uri to get the keywords from
- * @param iterator function to call on each keyword
- * @param iterator_cls closure for @a iterator
- * @return -1 if this is not a keyword URI, otherwise number of
- * keywords iterated over until iterator aborted
- */
- int
- GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
- GNUNET_FS_KeywordIterator iterator,
- void *iterator_cls);
- /**
- * Obtain the identity of the peer offering the data
- *
- * @param uri the location URI to inspect
- * @param peer where to store the identify of the peer (presumably) offering the content
- * @return #GNUNET_SYSERR if this is not a location URI, otherwise #GNUNET_OK
- */
- int
- GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
- struct GNUNET_PeerIdentity *peer);
- /**
- * Obtain the URI of the content itself.
- *
- * @param uri location URI to get the content URI from
- * @return NULL if argument is not a location URI
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri);
- /**
- * Obtain the expiration of the LOC URI.
- *
- * @param uri location URI to get the expiration from
- * @return expiration time of the URI
- */
- struct GNUNET_TIME_Absolute
- GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
- /**
- * Construct a location URI (this peer will be used for the location).
- * This function should only be called from within gnunet-service-fs,
- * as it requires the peer's private key which is generally unavailable
- * to processes directly under the user's control. However, for
- * testing and as it logically fits under URIs, it is in this API.
- *
- * @param base_uri content offered by the sender
- * @param sign_key private key of the peer
- * @param expiration_time how long will the content be offered?
- * @return the location URI, NULL on error
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *base_uri,
- const struct GNUNET_CRYPTO_EddsaPrivateKey *sign_key,
- struct GNUNET_TIME_Absolute expiration_time);
- /**
- * Merge the sets of keywords from two KSK URIs.
- *
- * @param u1 first uri
- * @param u2 second uri
- * @return merged URI, NULL on error
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_ksk_merge (const struct GNUNET_FS_Uri *u1,
- const struct GNUNET_FS_Uri *u2);
- /**
- * Duplicate URI.
- *
- * @param uri the URI to duplicate
- * @return copy of the URI
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
- /**
- * Create an FS URI from a single user-supplied string of keywords.
- * The string is broken up at spaces into individual keywords.
- * Keywords that start with "+" are mandatory. Double-quotes can
- * be used to prevent breaking up strings at spaces (and also
- * to specify non-mandatory keywords starting with "+").
- *
- * Keywords must contain a balanced number of double quotes and
- * double quotes can not be used in the actual keywords (for
- * example, the string '""foo bar""' will be turned into two
- * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'.
- *
- * @param keywords the keyword string
- * @param emsg where to store an error message
- * @return an FS URI for the given keywords, NULL
- * if keywords is not legal (i.e. empty).
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_ksk_create (const char *keywords,
- char **emsg);
- /**
- * Create an FS URI from a user-supplied command line of keywords.
- * Arguments should start with "+" to indicate mandatory
- * keywords.
- *
- * @param argc number of keywords
- * @param argv keywords (double quotes are not required for
- * keywords containing spaces; however, double
- * quotes are required for keywords starting with
- * "+"); there is no mechanism for having double
- * quotes in the actual keywords (if the user
- * did specifically specify double quotes, the
- * caller should convert each double quote
- * into two single quotes).
- * @return an FS URI for the given keywords, NULL
- * if keywords is not legal (i.e. empty).
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_ksk_create_from_args (unsigned int argc,
- const char **argv);
- /**
- * Test if two URIs are equal.
- *
- * @param u1 one of the URIs
- * @param u2 the other URI
- * @return #GNUNET_YES if the URIs are equal
- */
- int
- GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
- const struct GNUNET_FS_Uri *u2);
- /**
- * Is this a namespace URI?
- *
- * @param uri the uri to check
- * @return #GNUNET_YES if this is an SKS uri
- */
- int
- GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
- /**
- * Create an SKS URI from a namespace ID and an identifier.
- *
- * @param ns pseudonym to use
- * @param id identifier
- * @return an FS URI for the given namespace and identifier
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_sks_create (const struct GNUNET_CRYPTO_EcdsaPublicKey *ns,
- const char *id);
- /**
- * Get the public key of a namespace from the given
- * namespace URI.
- *
- * @param uri the uri to get the namespace ID from
- * @param pseudonym where to store the public key of the namespace
- * @return #GNUNET_OK on success
- */
- int
- GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
- struct GNUNET_CRYPTO_EcdsaPublicKey *pseudonym);
- /**
- * Get the content identifier of an SKS URI.
- *
- * @param uri the sks uri
- * @return NULL on error (not a valid SKS URI)
- */
- char *
- GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
- /**
- * Is this a keyword URI?
- *
- * @param uri the uri
- * @return #GNUNET_YES if this is a KSK uri
- */
- int
- GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
- /**
- * Is this a file (or directory) URI?
- *
- * @param uri the uri to check
- * @return #GNUNET_YES if this is a CHK uri
- */
- int
- GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
- /**
- * What is the size of the file that this URI
- * refers to?
- *
- * @param uri the CHK (or LOC) URI to inspect
- * @return size of the file as specified in the CHK URI
- */
- uint64_t
- GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
- /**
- * Is this a location URI?
- *
- * @param uri the uri to check
- * @return #GNUNET_YES if this is a LOC uri
- */
- int
- GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
- /**
- * Construct a keyword-URI from meta-data (take all entries
- * in the meta-data and construct one large keyword URI
- * that lists all keywords that can be found in the meta-data).
- *
- * @param md metadata to use
- * @return NULL on error, otherwise a KSK URI
- */
- struct GNUNET_FS_Uri *
- GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
- *md);
- /* ******************** command-line option parsing API *********************** */
- /**
- * Allow user to specify keywords.
- *
- * @param shortName short name of the option
- * @param name long name of the option
- * @param argumentHelp help text for the option argument
- * @param description long help text for the option
- * @param[out] topKeywords set to the desired value
- */
- struct GNUNET_GETOPT_CommandLineOption
- GNUNET_FS_GETOPT_KEYWORDS (char shortName,
- const char *name,
- const char *argumentHelp,
- const char *description,
- struct GNUNET_FS_Uri **topKeywords);
- /**
- * Allow user to specify metadata.
- *
- * @param shortName short name of the option
- * @param name long name of the option
- * @param argumentHelp help text for the option argument
- * @param description long help text for the option
- * @param[out] metadata set to the desired value
- */
- struct GNUNET_GETOPT_CommandLineOption
- GNUNET_FS_GETOPT_METADATA (char shortName,
- const char *name,
- const char *argumentHelp,
- const char *description,
- struct GNUNET_CONTAINER_MetaData **meta);
- /**
- * Command-line option parser function that allows the user to specify
- * one or more '-m' options with metadata. Each specified entry of
- * the form "type=value" will be added to the metadata. A pointer to
- * the metadata must be passed as the "scls" argument.
- *
- * @param ctx command line processor context
- * @param scls must be of type `struct GNUNET_CONTAINER_MetaData **`
- * @param option name of the option (typically 'k')
- * @param value command line argument given
- * @return #GNUNET_OK on success
- */
- int
- GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
- void *scls,
- const char *option,
- const char *value);
- /* ************************* sharing API ***************** */
- /**
- * Possible status codes used in the callback for the
- * various file-sharing operations. On each file (or search),
- * the callback is guaranteed to be called once with "START"
- * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED
- * are optional and depend on the circumstances; parent operations
- * will be STARTED before child-operations and STOPPED after
- * their respective child-operations. START and STOP signals
- * are typically generated either due to explicit client requests
- * or because of suspend/resume operations.
- */
- enum GNUNET_FS_Status
- {
- /**
- * Notification that we have started to publish a file structure.
- */
- GNUNET_FS_STATUS_PUBLISH_START = 0,
- /**
- * Notification that we have resumed sharing a file structure.
- */
- GNUNET_FS_STATUS_PUBLISH_RESUME = 1,
- /**
- * Notification that we have suspended sharing a file structure.
- */
- GNUNET_FS_STATUS_PUBLISH_SUSPEND = 2,
- /**
- * Notification that we are making progress sharing a file structure.
- */
- GNUNET_FS_STATUS_PUBLISH_PROGRESS = 3,
- /**
- * Notification that an error was encountered sharing a file structure.
- * The application will continue to receive resume/suspend events for
- * this structure until "GNUNET_FS_publish_stop" is called.
- */
- GNUNET_FS_STATUS_PUBLISH_ERROR = 4,
- /**
- * Notification that we completed sharing a file structure.
- * The application will continue to receive resume/suspend events for
- * this structure until "GNUNET_FS_publish_stop" is called.
- */
- GNUNET_FS_STATUS_PUBLISH_COMPLETED = 5,
- /**
- * Notification that we have stopped
- * the process of uploading a file structure; no
- * futher events will be generated for this action.
- */
- GNUNET_FS_STATUS_PUBLISH_STOPPED = 6,
- /**
- * Notification that we have started this download.
- */
- GNUNET_FS_STATUS_DOWNLOAD_START = 7,
- /**
- * Notification that this download is being resumed.
- */
- GNUNET_FS_STATUS_DOWNLOAD_RESUME = 8,
- /**
- * Notification that this download was suspended.
- */
- GNUNET_FS_STATUS_DOWNLOAD_SUSPEND = 9,
- /**
- * Notification about progress with this download.
- */
- GNUNET_FS_STATUS_DOWNLOAD_PROGRESS = 10,
- /**
- * Notification that this download encountered an error.
- */
- GNUNET_FS_STATUS_DOWNLOAD_ERROR = 11,
- /**
- * Notification that this download completed. Note that for
- * directories, completion does not imply completion of all files in
- * the directory.
- */
- GNUNET_FS_STATUS_DOWNLOAD_COMPLETED = 12,
- /**
- * Notification that this download was stopped
- * (final event with respect to this action).
- */
- GNUNET_FS_STATUS_DOWNLOAD_STOPPED = 13,
- /**
- * Notification that this download is now actively being
- * pursued (as opposed to waiting in the queue).
- */
- GNUNET_FS_STATUS_DOWNLOAD_ACTIVE = 14,
- /**
- * Notification that this download is no longer actively
- * being pursued (back in the queue).
- */
- GNUNET_FS_STATUS_DOWNLOAD_INACTIVE = 15,
- /**
- * Notification that this download is no longer part of a
- * recursive download or search but now a 'stand-alone'
- * download (and may thus need to be moved in the GUI
- * into a different category).
- */
- GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT = 16,
- /**
- * First event generated when a client requests
- * a search to begin or when a namespace result
- * automatically triggers the search for updates.
- */
- GNUNET_FS_STATUS_SEARCH_START = 17,
- /**
- * Last event when a search is being resumed;
- * note that "GNUNET_FS_SEARCH_START" will not
- * be generated in this case.
- */
- GNUNET_FS_STATUS_SEARCH_RESUME = 18,
- /**
- * Event generated for each search result
- * when the respective search is resumed.
- */
- GNUNET_FS_STATUS_SEARCH_RESUME_RESULT = 19,
- /**
- * Last event when a search is being suspended;
- * note that "GNUNET_FS_SEARCH_STOPPED" will not
- * be generated in this case.
- */
- GNUNET_FS_STATUS_SEARCH_SUSPEND = 20,
- /**
- * This search has yielded a result.
- */
- GNUNET_FS_STATUS_SEARCH_RESULT = 21,
- /**
- * We have discovered a new namespace.
- */
- GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE = 22,
- /**
- * We have additional data about the quality
- * or availability of a search result.
- */
- GNUNET_FS_STATUS_SEARCH_UPDATE = 23,
- /**
- * Signals a problem with this search.
- */
- GNUNET_FS_STATUS_SEARCH_ERROR = 24,
- /**
- * Signals that this search was paused.
- */
- GNUNET_FS_STATUS_SEARCH_PAUSED = 25,
- /**
- * Signals that this search was continued (unpaused).
- */
- GNUNET_FS_STATUS_SEARCH_CONTINUED = 26,
- /**
- * Event generated for each search result
- * when the respective search is stopped.
- */
- GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED = 27,
- /**
- * Event generated for each search result
- * when the respective search is suspended.
- */
- GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND = 28,
- /**
- * Last message from a search; this signals
- * that there will be no further events associated
- * with this search.
- */
- GNUNET_FS_STATUS_SEARCH_STOPPED = 29,
- /**
- * Notification that we started to unindex a file.
- */
- GNUNET_FS_STATUS_UNINDEX_START = 30,
- /**
- * Notification that we resumed unindexing of a file.
- */
- GNUNET_FS_STATUS_UNINDEX_RESUME = 31,
- /**
- * Notification that we suspended unindexing a file.
- */
- GNUNET_FS_STATUS_UNINDEX_SUSPEND = 32,
- /**
- * Notification that we made progress unindexing a file.
- */
- GNUNET_FS_STATUS_UNINDEX_PROGRESS = 33,
- /**
- * Notification that we encountered an error unindexing
- * a file.
- */
- GNUNET_FS_STATUS_UNINDEX_ERROR = 34,
- /**
- * Notification that the unindexing of this file
- * was completed.
- */
- GNUNET_FS_STATUS_UNINDEX_COMPLETED = 35,
- /**
- * Notification that the unindexing of this file
- * was stopped (final event for this action).
- */
- GNUNET_FS_STATUS_UNINDEX_STOPPED = 36,
- /**
- * Notification that we are making progress sharing a directory.
- */
- GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY = 37
- };
- /**
- * Handle for controlling an upload.
- */
- struct GNUNET_FS_PublishContext;
- /**
- * Handle for controlling an unindexing operation.
- */
- struct GNUNET_FS_UnindexContext;
- /**
- * Handle for controlling a search.
- */
- struct GNUNET_FS_SearchContext;
- /**
- * Result from a search. Opaque handle to refer to the search
- * (typically used when starting a download associated with the search
- * result).
- */
- struct GNUNET_FS_SearchResult;
- /**
- * Context for controlling a download.
- */
- struct GNUNET_FS_DownloadContext;
- /**
- * Handle for detail information about a file that is being publishd.
- * Specifies metadata, keywords, how to get the contents of the file
- * (i.e. data-buffer in memory, filename on disk) and other options.
- */
- struct GNUNET_FS_FileInformation;
- /**
- * Argument given to the progress callback with
- * information about what is going on.
- */
- struct GNUNET_FS_ProgressInfo
- {
- /**
- * Values that depend on the event type.
- */
- union
- {
- /**
- * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events.
- */
- struct
- {
- /**
- * Context for controlling the upload.
- */
- struct GNUNET_FS_PublishContext *pc;
- /**
- * Information about the file that is being publishd.
- */
- const struct GNUNET_FS_FileInformation *fi;
- /**
- * Client context pointer (set the last time by the client for
- * this operation; initially NULL on START/RESUME events).
- */
- void *cctx;
- /**
- * Client context pointer for the parent operation
- * (if this is a file in a directory or a subdirectory).
- */
- void *pctx;
- /**
- * Name of the file being published; can be NULL.
- */
- const char *filename;
- /**
- * How large is the file overall? For directories,
- * this is only the size of the directory itself,
- * not of the other files contained within the
- * directory.
- */
- uint64_t size;
- /**
- * At what time do we expect to finish the upload?
- * (will be a value in the past for completed
- * uploads).
- */
- struct GNUNET_TIME_Relative eta;
- /**
- * How long has this upload been actively running
- * (excludes times where the upload was suspended).
- */
- struct GNUNET_TIME_Relative duration;
- /**
- * How many bytes have we completed?
- */
- uint64_t completed;
- /**
- * What anonymity level is used for this upload?
- */
- uint32_t anonymity;
- /**
- * Additional values for specific events.
- */
- union
- {
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
- */
- struct
- {
- /**
- * Data block we just published.
- */
- const void *data;
- /**
- * At what offset in the file is "data"?
- */
- uint64_t offset;
- /**
- * Length of the data block.
- */
- uint64_t data_len;
- /**
- * Depth of the given block in the tree;
- * 0 would be the lowest level (DBLOCKs).
- */
- unsigned int depth;
- } progress;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY events.
- */
- struct
- {
- /**
- * How far are we along in the overall directory?
- */
- uint64_t completed;
- /**
- * How big do we estimate the entire directory to be?
- */
- uint64_t total;
- /**
- * At what time do we expect to finish the upload of the
- * CONTENTS of the directory. (The direcory itself will take
- * extra time, indicated with the "eta" member at the
- * "publish"-level of this struct.)
- */
- struct GNUNET_TIME_Relative eta;
- } progress_directory;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_PUBLISH_RESUME events.
- */
- struct
- {
- /**
- * Error message, NULL if no error was encountered so far.
- */
- const char *message;
- /**
- * URI of the file (if the download had been completed)
- */
- const struct GNUNET_FS_Uri *chk_uri;
- /**
- * SKS URI of the file (if the download had been completed)
- */
- const struct GNUNET_FS_Uri *sks_uri;
- } resume;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
- */
- struct
- {
- /**
- * CHK URI of the file.
- */
- const struct GNUNET_FS_Uri *chk_uri;
- /**
- * SKS URI of the file (if the download had been completed)
- */
- const struct GNUNET_FS_Uri *sks_uri;
- } completed;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_PUBLISH_ERROR events.
- */
- struct
- {
- /**
- * Error message, never NULL.
- */
- const char *message;
- } error;
- } specifics;
- } publish;
- /**
- * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
- */
- struct
- {
- /**
- * Context for controlling the download.
- */
- struct GNUNET_FS_DownloadContext *dc;
- /**
- * Client context pointer (set the last time
- * by the client for this operation; initially
- * NULL on START/RESUME events).
- */
- void *cctx;
- /**
- * Client context pointer for the parent operation
- * (if this is a file in a directory or a subdirectory).
- */
- void *pctx;
- /**
- * Client context pointer for the associated search operation
- * (specifically, context pointer for the specific search
- * result, not the overall search); only set if this
- * download was started from a search result.
- */
- void *sctx;
- /**
- * URI used for this download.
- */
- const struct GNUNET_FS_Uri *uri;
- /**
- * Name of the file that we are downloading.
- */
- const char *filename;
- /**
- * How large is the download overall? This
- * is NOT necessarily the size from the
- * URI since we may be doing a partial download.
- */
- uint64_t size;
- /**
- * At what time do we expect to finish the download?
- * (will be a value in the past for completed
- * uploads).
- */
- struct GNUNET_TIME_Relative eta;
- /**
- * How long has this download been active?
- */
- struct GNUNET_TIME_Relative duration;
- /**
- * How many bytes have we completed?
- */
- uint64_t completed;
- /**
- * What anonymity level is used for this download?
- */
- uint32_t anonymity;
- /**
- * Is the download currently active.
- */
- int is_active;
- /**
- * Additional values for specific events.
- */
- union
- {
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
- */
- struct
- {
- /**
- * Data block we just obtained, can be NULL (even if
- * data_len > 0) if we found the entire block 'intact' on
- * disk. In this case, it is also possible for 'data_len'
- * to be larger than an individual (32k) block.
- */
- const void *data;
- /**
- * At what offset in the file is "data"?
- */
- uint64_t offset;
- /**
- * Length of the data block.
- */
- uint64_t data_len;
- /**
- * How much time passed between us asking for this block and
- * actually getting it? #GNUNET_TIME_UNIT_FOREVER_REL if unknown.
- */
- struct GNUNET_TIME_Relative block_download_duration;
- /**
- * Depth of the given block in the tree;
- * 0 would be the lowest level (DBLOCKS).
- */
- unsigned int depth;
- /**
- * How much respect did we offer for downloading this block? (estimate,
- * because we might have the same request pending for multiple clients,
- * and of course because a transmission may have failed at a lower
- * layer).
- */
- uint32_t respect_offered;
- /**
- * How often did we transmit the request? (estimate,
- * because we might have the same request pending for multiple clients,
- * and of course because a transmission may have failed at a lower
- * layer).
- */
- uint32_t num_transmissions;
- } progress;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_DOWNLOAD_START events.
- */
- struct
- {
- /**
- * Known metadata for the download.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- } start;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
- */
- struct
- {
- /**
- * Known metadata for the download.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * Error message, NULL if we have not encountered any error yet.
- */
- const char *message;
- } resume;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
- */
- struct
- {
- /**
- * Error message.
- */
- const char *message;
- } error;
- } specifics;
- } download;
- /**
- * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
- */
- struct
- {
- /**
- * Context for controlling the search, NULL for
- * searches that were not explicitly triggered
- * by the client (i.e., searches for updates in
- * namespaces).
- */
- struct GNUNET_FS_SearchContext *sc;
- /**
- * Client context pointer (set the last time by the client for
- * this operation; initially NULL on START/RESUME events). Note
- * that this value can only be set on START/RESUME; returning
- * non-NULL on RESULT/RESUME_RESULT will actually update the
- * private context for "UPDATE" events.
- */
- void *cctx;
- /**
- * Client parent-context pointer; NULL for top-level searches,
- * refers to the client context of the associated search result
- * for automatically triggered searches for updates in
- * namespaces. In this case, 'presult' refers to that search
- * result.
- */
- void *pctx;
- /**
- * What query is used for this search
- * (list of keywords or SKS identifier).
- */
- const struct GNUNET_FS_Uri *query;
- /**
- * How long has this search been actively running
- * (excludes times where the search was paused or
- * suspended).
- */
- struct GNUNET_TIME_Relative duration;
- /**
- * What anonymity level is used for this search?
- */
- uint32_t anonymity;
- /**
- * Additional values for specific events.
- */
- union
- {
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_RESULT events.
- */
- struct
- {
- /**
- * Metadata for the search result.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * URI for the search result.
- */
- const struct GNUNET_FS_Uri *uri;
- /**
- * Handle to the result (for starting downloads).
- */
- struct GNUNET_FS_SearchResult *result;
- /**
- * Applicability rank (the larger, the better the result
- * fits the search criteria).
- */
- uint32_t applicability_rank;
- } result;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
- */
- struct
- {
- /**
- * Metadata for the search result.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * URI for the search result.
- */
- const struct GNUNET_FS_Uri *uri;
- /**
- * Handle to the result (for starting downloads).
- */
- struct GNUNET_FS_SearchResult *result;
- /**
- * Current availability rank (negative:
- * unavailable, positive: available)
- */
- int32_t availability_rank;
- /**
- * On how many total queries is the given
- * availability_rank based?
- */
- uint32_t availability_certainty;
- /**
- * Updated applicability rank (the larger,
- * the better the result fits the search
- * criteria).
- */
- uint32_t applicability_rank;
- } resume_result;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_UPDATE events.
- */
- struct
- {
- /**
- * Private context set for for this result
- * during the "RESULT" event.
- */
- void *cctx;
- /**
- * Metadata for the search result.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * URI for the search result.
- */
- const struct GNUNET_FS_Uri *uri;
- /**
- * Current availability rank (negative:
- * unavailable, positive: available)
- */
- int32_t availability_rank;
- /**
- * On how many total queries is the given
- * availability_rank based?
- */
- uint32_t availability_certainty;
- /**
- * Updated applicability rank (the larger,
- * the better the result fits the search
- * criteria).
- */
- uint32_t applicability_rank;
- /**
- * How long has the current probe been active?
- */
- struct GNUNET_TIME_Relative current_probe_time;
- } update;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
- * These events are automatically triggered for
- * each search result before the
- * #GNUNET_FS_STATUS_SEARCH_SUSPEND event. This
- * happens primarily to give the client a chance
- * to clean up the "cctx" (if needed).
- */
- struct
- {
- /**
- * Private context set for for this result
- * during the "RESULT" event.
- */
- void *cctx;
- /**
- * Metadata for the search result.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * URI for the search result.
- */
- const struct GNUNET_FS_Uri *uri;
- } result_suspend;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
- * These events are automatically triggered for
- * each search result before the
- * #GNUNET_FS_STATUS_SEARCH_STOPPED event. This
- * happens primarily to give the client a chance
- * to clean up the "cctx" (if needed).
- */
- struct
- {
- /**
- * Private context set for for this result
- * during the "RESULT" event.
- */
- void *cctx;
- /**
- * Metadata for the search result.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * URI for the search result.
- */
- const struct GNUNET_FS_Uri *uri;
- } result_stopped;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_RESUME events.
- */
- struct
- {
- /**
- * Error message, NULL if we have not encountered any error yet.
- */
- const char *message;
- /**
- * Is this search currently paused?
- */
- int is_paused;
- } resume;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_SEARCH_ERROR events.
- */
- struct
- {
- /**
- * Error message.
- */
- const char *message;
- } error;
- /**
- * Values for #GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE events.
- */
- struct
- {
- /**
- * Short, human-readable name of the namespace.
- */
- const char *name;
- /**
- * Root identifier for the namespace, can be NULL.
- */
- const char *root;
- /**
- * Metadata for the namespace.
- */
- const struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * Public key of the namespace.
- */
- struct GNUNET_CRYPTO_EcdsaPublicKey pseudonym;
- } ns;
- } specifics;
- } search;
- /**
- * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
- */
- struct
- {
- /**
- * Context for controlling the unindexing.
- */
- struct GNUNET_FS_UnindexContext *uc;
- /**
- * Client context pointer (set the last time
- * by the client for this operation; initially
- * NULL on START/RESUME events).
- */
- void *cctx;
- /**
- * Name of the file that is being unindexed.
- */
- const char *filename;
- /**
- * How large is the file overall?
- */
- uint64_t size;
- /**
- * At what time do we expect to finish unindexing?
- * (will be a value in the past for completed
- * unindexing opeations).
- */
- struct GNUNET_TIME_Relative eta;
- /**
- * How long has this upload been actively running
- * (excludes times where the upload was suspended).
- */
- struct GNUNET_TIME_Relative duration;
- /**
- * How many bytes have we completed?
- */
- uint64_t completed;
- /**
- * Additional values for specific events.
- */
- union
- {
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
- */
- struct
- {
- /**
- * Data block we just unindexed.
- */
- const void *data;
- /**
- * At what offset in the file is "data"?
- */
- uint64_t offset;
- /**
- * Length of the data block.
- */
- uint64_t data_len;
- /**
- * Depth of the given block in the tree;
- * 0 would be the lowest level (DBLOCKS).
- */
- unsigned int depth;
- } progress;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_UNINDEX_RESUME events.
- */
- struct
- {
- /**
- * Error message, NULL if we have not encountered any error yet.
- */
- const char *message;
- } resume;
- /**
- * These values are only valid for
- * #GNUNET_FS_STATUS_UNINDEX_ERROR events.
- */
- struct
- {
- /**
- * Error message.
- */
- const char *message;
- } error;
- } specifics;
- } unindex;
- } value;
- /**
- * Specific status code (determines the event type).
- */
- enum GNUNET_FS_Status status;
- /**
- * File-sharing handle that generated the event.
- */
- struct GNUNET_FS_Handle *fsh;
- };
- /**
- * Notification of FS to a client about the progress of an
- * operation. Callbacks of this type will be used for uploads,
- * downloads and searches. Some of the arguments depend a bit
- * in their meaning on the context in which the callback is used.
- *
- * @param cls closure
- * @param info details about the event, specifying the event type
- * and various bits about the event
- * @return client-context (for the next progress call
- * for this operation; should be set to NULL for
- * SUSPEND and STOPPED events). The value returned
- * will be passed to future callbacks in the respective
- * field in the `struct GNUNET_FS_ProgressInfo`.
- */
- typedef void *
- (*GNUNET_FS_ProgressCallback) (void *cls,
- const struct GNUNET_FS_ProgressInfo *info);
- /**
- * General (global) option flags for file-sharing.
- */
- enum GNUNET_FS_Flags
- {
- /**
- * No special flags set.
- */
- GNUNET_FS_FLAGS_NONE = 0,
- /**
- * Is persistence of operations desired?
- * (will create SUSPEND/RESUME events).
- */
- GNUNET_FS_FLAGS_PERSISTENCE = 1,
- /**
- * Should we automatically trigger probes for search results
- * to determine availability?
- * (will create #GNUNET_FS_STATUS_SEARCH_UPDATE events).
- */
- GNUNET_FS_FLAGS_DO_PROBES = 2
- };
- /**
- * Options specified in the VARARGs portion of GNUNET_FS_start.
- */
- enum GNUNET_FS_OPTIONS
- {
- /**
- * Last option in the VARARG list.
- */
- GNUNET_FS_OPTIONS_END = 0,
- /**
- * Select the desired amount of parallelism (this option should be
- * followed by an "unsigned int" giving the desired maximum number
- * of parallel downloads).
- */
- GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1,
- /**
- * Maximum number of requests that should be pending at a given
- * point in time (invidivual downloads may go above this, but
- * if we are above this threshold, we should not activate any
- * additional downloads.
- */
- GNUNET_FS_OPTIONS_REQUEST_PARALLELISM = 2
- };
- /**
- * Settings for publishing a block (which may of course also
- * apply to an entire directory or file).
- */
- struct GNUNET_FS_BlockOptions
- {
- /**
- * At what time should the block expire? Data blocks (DBLOCKS and
- * IBLOCKS) may still be used even if they are expired (however,
- * they'd be removed quickly from the datastore if we are short on
- * space), all other types of blocks will no longer be returned
- * after they expire.
- */
- struct GNUNET_TIME_Absolute expiration_time;
- /**
- * At which anonymity level should the block be shared?
- * (0: no anonymity, 1: normal GAP, >1: with cover traffic).
- */
- uint32_t anonymity_level;
- /**
- * How important is it for us to store the block? If we run
- * out of space, the highest-priority, non-expired blocks will
- * be kept.
- */
- uint32_t content_priority;
- /**
- * How often should we try to migrate the block to other peers?
- * Only used if "CONTENT_PUSHING" is set to YES, in which case we
- * first push each block to other peers according to their
- * replication levels. Once each block has been pushed that many
- * times to other peers, blocks are chosen for migration at random.
- * Naturally, there is no guarantee that the other peers will keep
- * these blocks for any period of time (since they won't have any
- * priority or might be too busy to even store the block in the
- * first place).
- */
- uint32_t replication_level;
- };
- /**
- * Handle to the file-sharing service.
- */
- struct GNUNET_FS_Handle;
- /**
- * Setup a connection to the file-sharing service.
- *
- * @param cfg configuration to use
- * @param client_name unique identifier for this client
- * @param upcb function to call to notify about FS actions
- * @param upcb_cls closure for @a upcb
- * @param flags specific attributes for fs-operations
- * @param ... list of optional options, terminated with #GNUNET_FS_OPTIONS_END
- * @return NULL on error
- */
- struct GNUNET_FS_Handle *
- GNUNET_FS_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const char *client_name,
- GNUNET_FS_ProgressCallback upcb,
- void *upcb_cls,
- enum GNUNET_FS_Flags flags,
- ...);
- /**
- * Close our connection with the file-sharing service.
- * The callback given to #GNUNET_FS_start() will no longer be
- * called after this function returns.
- * This function MUST NOT be called from within the
- * callback itself.
- *
- * @param h handle that was returned from #GNUNET_FS_start()
- */
- void
- GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
- /**
- * Function called on entries in a `struct GNUNET_FS_FileInformation` iteration.
- *
- * @param cls closure
- * @param fi the entry in the publish-structure
- * @param length length of the file or directory
- * @param meta metadata for the file or directory (can be modified)
- * @param uri pointer to the keywords that will be used for this entry (can be modified)
- * @param bo block options (can be modified)
- * @param do_index should we index (can be modified)
- * @param client_info pointer to client context set upon creation (can be modified)
- * @return #GNUNET_OK to continue, #GNUNET_NO to remove
- * this entry from the directory, #GNUNET_SYSERR
- * to abort the iteration
- */
- typedef int
- (*GNUNET_FS_FileInformationProcessor) (void *cls,
- struct GNUNET_FS_FileInformation *fi,
- uint64_t length,
- struct GNUNET_CONTAINER_MetaData *meta,
- struct GNUNET_FS_Uri ** uri,
- struct GNUNET_FS_BlockOptions *bo,
- int *do_index,
- void **client_info);
- /**
- * Obtain the name under which this file information
- * structure is stored on disk. Only works for top-level
- * file information structures.
- *
- * @param s structure to get the filename for
- * @return NULL on error, otherwise filename that can be used
- * to read this fi-struct from disk.
- */
- const char *
- GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
- /**
- * Obtain the filename from the file information structure.
- *
- * @param s structure to get the filename for
- * @return "filename" field of the structure (can be NULL)
- */
- const char *
- GNUNET_FS_file_information_get_filename (struct GNUNET_FS_FileInformation *s);
- /**
- * Set the filename in the file information structure.
- * If filename was already set, frees it before setting the new one.
- * Makes a copy of the argument.
- *
- * @param s structure to get the filename for
- * @param filename filename to set
- */
- void
- GNUNET_FS_file_information_set_filename (struct GNUNET_FS_FileInformation *s,
- const char *filename);
- /**
- * Create an entry for a file in a publish-structure.
- *
- * @param h handle to the file sharing subsystem
- * @param client_info initial client-info value for this entry
- * @param filename name of the file or directory to publish
- * @param keywords under which keywords should this file be available
- * directly; can be NULL
- * @param meta metadata for the file
- * @param do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
- * #GNUNET_SYSERR for simulation
- * @param bo block options
- * @return publish structure entry for the file
- */
- struct GNUNET_FS_FileInformation *
- GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
- void *client_info,
- const char *filename,
- const struct GNUNET_FS_Uri *keywords,
- const struct GNUNET_CONTAINER_MetaData *meta,
- int do_index,
- const struct GNUNET_FS_BlockOptions *bo);
- /**
- * Create an entry for a file in a publish-structure.
- *
- * @param h handle to the file sharing subsystem
- * @param client_info initial client-info value for this entry
- * @param length length of the file
- * @param data data for the file (should not be used afterwards by
- * the caller; callee will "free")
- * @param keywords under which keywords should this file be available
- * directly; can be NULL
- * @param meta metadata for the file
- * @param do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
- * #GNUNET_SYSERR for simulation
- * @param bo block options
- * @return publish structure entry for the file
- */
- struct GNUNET_FS_FileInformation *
- GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
- void *client_info,
- uint64_t length,
- void *data,
- const struct GNUNET_FS_Uri *keywords,
- const struct GNUNET_CONTAINER_MetaData *meta,
- int do_index,
- const struct GNUNET_FS_BlockOptions *bo);
- /**
- * Function that provides data.
- *
- * @param cls closure
- * @param offset offset to read from; it is possible
- * that the caller might need to go backwards
- * a bit at times; set to UINT64_MAX to tell
- * the reader that we won't be reading for a while
- * (used to close the file descriptor but NOT fully
- * clean up the reader's state); in this case,
- * a value of '0' for max should be ignored
- * @param max maximum number of bytes that should be
- * copied to buf; readers are not allowed
- * to provide less data unless there is an error;
- * a value of "0" will be used at the end to allow
- * the reader to clean up its internal state
- * @param buf where the reader should write the data
- * @param emsg location for the reader to store an error message
- * @return number of bytes written, usually @a max, 0 on error
- */
- typedef size_t
- (*GNUNET_FS_DataReader) (void *cls,
- uint64_t offset,
- size_t max,
- void *buf,
- char **emsg);
- /**
- * Create an entry for a file in a publish-structure.
- *
- * @param h handle to the file sharing subsystem
- * @param client_info initial client-info value for this entry
- * @param length length of the file
- * @param reader function that can be used to obtain the data for the file
- * @param reader_cls closure for @a reader
- * @param keywords under which keywords should this file be available
- * directly; can be NULL
- * @param meta metadata for the file
- * @param do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
- * #GNUNET_SYSERR for simulation
- * @param bo block options
- * @return publish structure entry for the file
- */
- struct GNUNET_FS_FileInformation *
- GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
- void *client_info,
- uint64_t length,
- GNUNET_FS_DataReader reader,
- void *reader_cls,
- const struct GNUNET_FS_Uri
- *keywords,
- const struct
- GNUNET_CONTAINER_MetaData *meta,
- int do_index,
- const struct
- GNUNET_FS_BlockOptions *bo);
- /**
- * Create an entry for an empty directory in a publish-structure.
- *
- * @param h handle to the file sharing subsystem
- * @param client_info initial client-info value for this entry
- * @param keywords under which keywords should this directory be available
- * directly; can be NULL
- * @param meta metadata for the directory
- * @param bo block options
- * @param filename name of the directory; can be NULL
- * @return publish structure entry for the directory , NULL on error
- */
- struct GNUNET_FS_FileInformation *
- GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
- void *client_info,
- const struct GNUNET_FS_Uri
- *keywords,
- const struct
- GNUNET_CONTAINER_MetaData
- *meta,
- const struct
- GNUNET_FS_BlockOptions *bo,
- const char *filename);
- /**
- * Test if a given entry represents a directory.
- *
- * @param ent check if this FI represents a directory
- * @return #GNUNET_YES if so, #GNUNET_NO if not
- */
- int
- GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation
- *ent);
- /**
- * Add an entry to a directory in a publish-structure. Clients
- * should never modify publish structures that were passed to
- * #GNUNET_FS_publish_start() already.
- *
- * @param dir the directory
- * @param ent the entry to add; the entry must not have been
- * added to any other directory at this point and
- * must not include @a dir in its structure
- * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
- */
- int
- GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
- struct GNUNET_FS_FileInformation *ent);
- /**
- * Inspect a file or directory in a publish-structure. Clients
- * should never modify publish structures that were passed to
- * #GNUNET_FS_publish_start already. When called on a directory,
- * this function will FIRST call @a proc with information about
- * the directory itself and then for each of the files in the
- * directory (but not for files in subdirectories). When called
- * on a file, @a proc will be called exactly once (with information
- * about the specific file).
- *
- * @param dir the directory
- * @param proc function to call on each entry
- * @param proc_cls closure for @a proc
- */
- void
- GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
- GNUNET_FS_FileInformationProcessor proc,
- void *proc_cls);
- /**
- * Destroy publish-structure. Clients should never destroy publish
- * structures that were passed to #GNUNET_FS_publish_start already.
- *
- * @param fi structure to destroy
- * @param cleaner function to call on each entry in the structure
- * (useful to clean up client_info); can be NULL; return
- * values are ignored
- * @param cleaner_cls closure for @a cleaner
- */
- void
- GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
- GNUNET_FS_FileInformationProcessor cleaner,
- void *cleaner_cls);
- /**
- * Options for publishing. Compatible options
- * can be OR'ed together.
- */
- enum GNUNET_FS_PublishOptions
- {
- /**
- * No options (use defaults for everything).
- */
- GNUNET_FS_PUBLISH_OPTION_NONE = 0,
- /**
- * Simulate publishing. With this option, no data will be stored
- * in the datastore. Useful for computing URIs from files.
- */
- GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1
- };
- /**
- * Publish a file or directory.
- *
- * @param h handle to the file sharing subsystem
- * @param fi information about the file or directory structure to publish
- * @param ns namespace to publish the file in, NULL for no namespace
- * @param nid identifier to use for the publishd content in the namespace
- * (can be NULL, must be NULL if namespace is NULL)
- * @param nuid update-identifier that will be used for future updates
- * (can be NULL, must be NULL if namespace or nid is NULL)
- * @param options options for the publication
- * @return context that can be used to control the publish operation
- */
- struct GNUNET_FS_PublishContext *
- GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,
- struct GNUNET_FS_FileInformation *fi,
- const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
- const char *nid,
- const char *nuid,
- enum GNUNET_FS_PublishOptions options);
- /**
- * Stop a publication. Will abort incomplete publications (but
- * not remove blocks that have already been published) or
- * simply clean up the state for completed publications.
- * Must NOT be called from within the event callback!
- *
- * @param pc context for the publication to stop
- */
- void
- GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc);
- /**
- * Signature of a function called as the continuation of a KBlock or
- * SBlock publication.
- *
- * @param cls closure
- * @param uri URI under which the block is now available, NULL on error
- * @param emsg error message, NULL on success
- */
- typedef void
- (*GNUNET_FS_PublishContinuation) (void *cls,
- const struct GNUNET_FS_Uri *uri,
- const char *emsg);
- /**
- * Handle to cancel publish KSK operation.
- */
- struct GNUNET_FS_PublishKskContext;
- /**
- * Publish a KBlock on GNUnet.
- *
- * @param h handle to the file sharing subsystem
- * @param ksk_uri keywords to use
- * @param meta metadata to use
- * @param uri URI to refer to in the KBlock
- * @param bo block options
- * @param options publication options
- * @param cont continuation
- * @param cont_cls closure for @a cont
- * @return NULL on error (@a cont will still be called)
- */
- struct GNUNET_FS_PublishKskContext *
- GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
- const struct GNUNET_FS_Uri *ksk_uri,
- const struct GNUNET_CONTAINER_MetaData *meta,
- const struct GNUNET_FS_Uri *uri,
- const struct GNUNET_FS_BlockOptions *bo,
- enum GNUNET_FS_PublishOptions options,
- GNUNET_FS_PublishContinuation cont, void *cont_cls);
- /**
- * Abort the KSK publishing operation.
- *
- * @param pkc context of the operation to abort.
- */
- void
- GNUNET_FS_publish_ksk_cancel (struct GNUNET_FS_PublishKskContext *pkc);
- /**
- * Handle to cancel publish SKS operation.
- */
- struct GNUNET_FS_PublishSksContext;
- /**
- * Publish an SBlock on GNUnet.
- *
- * @param h handle to the file sharing subsystem
- * @param ns namespace to publish in
- * @param identifier identifier to use
- * @param update update identifier to use
- * @param meta metadata to use
- * @param uri URI to refer to in the SBlock
- * @param bo block options
- * @param options publication options
- * @param cont continuation
- * @param cont_cls closure for @a cont
- * @return NULL on error (@a cont will still be called)
- */
- struct GNUNET_FS_PublishSksContext *
- GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
- const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
- const char *identifier,
- const char *update,
- const struct GNUNET_CONTAINER_MetaData *meta,
- const struct GNUNET_FS_Uri *uri,
- const struct GNUNET_FS_BlockOptions *bo,
- enum GNUNET_FS_PublishOptions options,
- GNUNET_FS_PublishContinuation cont, void *cont_cls);
- /**
- * Abort the SKS publishing operation.
- *
- * @param psc context of the operation to abort.
- */
- void
- GNUNET_FS_publish_sks_cancel (struct GNUNET_FS_PublishSksContext *psc);
- /**
- * Type of a function called by #GNUNET_FS_get_indexed_files.
- *
- * @param cls closure
- * @param filename the name of the file, NULL for end of list
- * @param file_id hash of the contents of the indexed file
- * @return #GNUNET_OK to continue iteration, #GNUNET_SYSERR to abort
- */
- typedef int
- (*GNUNET_FS_IndexedFileProcessor) (void *cls,
- const char *filename,
- const struct GNUNET_HashCode *file_id);
- /**
- * Handle to cancel 'GNUNET_FS_get_indexed_files'.
- */
- struct GNUNET_FS_GetIndexedContext;
- /**
- * Iterate over all indexed files.
- *
- * @param h handle to the file sharing subsystem
- * @param iterator function to call on each indexed file
- * @param iterator_cls closure for @a iterator
- * @return NULL on error (@a iterator is not called)
- */
- struct GNUNET_FS_GetIndexedContext *
- GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
- GNUNET_FS_IndexedFileProcessor iterator,
- void *iterator_cls);
- /**
- * Cancel iteration over all indexed files.
- *
- * @param gic operation to cancel
- */
- void
- GNUNET_FS_get_indexed_files_cancel (struct GNUNET_FS_GetIndexedContext *gic);
- /**
- * Unindex a file.
- *
- * @param h handle to the file sharing subsystem
- * @param filename file to unindex
- * @param cctx initial value for the client context
- * @return NULL on error, otherwise handle
- */
- struct GNUNET_FS_UnindexContext *
- GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h,
- const char *filename,
- void *cctx);
- /**
- * Clean up after completion of an unindex operation.
- *
- * @param uc handle
- */
- void
- GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
- /**
- * Function called on updateable identifiers.
- *
- * @param cls closure
- * @param last_id last identifier
- * @param last_uri uri used for the content published under the @a last_id
- * @param last_meta metadata associated with @a last_uri
- * @param next_id identifier that should be used for updates
- */
- typedef void (*GNUNET_FS_IdentifierProcessor) (void *cls,
- const char *last_id,
- const struct GNUNET_FS_Uri *last_uri,
- const struct GNUNET_CONTAINER_MetaData *last_meta,
- const char *next_id);
- /**
- * List all of the identifiers in the namespace for which we could
- * produce an update. Namespace updates form a graph where each node
- * has a name. Each node can have any number of URI/meta-data entries
- * which can each be linked to other nodes. Cycles are possible.
- *
- * Calling this function with @a next_id NULL will cause the library to
- * call @a ip with a root for each strongly connected component of the
- * graph (a root being a node from which all other nodes in the Scc
- * are reachable).
- *
- * Calling this function with @a next_id being the name of a node will
- * cause the library to call @a ip with all children of the node. Note
- * that cycles within an SCC are possible (including self-loops).
- *
- * @param h fs handle to use
- * @param ns namespace to inspect for updateable content
- * @param next_id ID to look for; use NULL to look for SCC roots
- * @param ip function to call on each updateable identifier
- * @param ip_cls closure for @a ip
- */
- void
- GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Handle *h,
- const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
- const char *next_id,
- GNUNET_FS_IdentifierProcessor ip,
- void *ip_cls);
- /**
- * Options for searching. Compatible options
- * can be OR'ed together.
- */
- enum GNUNET_FS_SearchOptions
- {
- /**
- * No options (use defaults for everything).
- */
- GNUNET_FS_SEARCH_OPTION_NONE = 0,
- /**
- * Only search the local host, do not search remote systems (no P2P)
- */
- GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1
- };
- /**
- * Start search for content.
- *
- * @param h handle to the file sharing subsystem
- * @param uri specifies the search parameters; can be
- * a KSK URI or an SKS URI.
- * @param anonymity desired level of anonymity
- * @param options options for the search
- * @param cctx initial value for the client context
- * @return context that can be used to control the search
- */
- struct GNUNET_FS_SearchContext *
- GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
- const struct GNUNET_FS_Uri *uri, uint32_t anonymity,
- enum GNUNET_FS_SearchOptions options, void *cctx);
- /**
- * Pause search.
- *
- * @param sc context for the search that should be paused
- */
- void
- GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
- /**
- * Continue paused search.
- *
- * @param sc context for the search that should be resumed
- */
- void
- GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
- /**
- * Stop search for content.
- *
- * @param sc context for the search that should be stopped
- */
- void
- GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
- /**
- * Start download probes for the given search result.
- *
- * @param h file-sharing handle to use for the operation
- * @param uri URI to probe
- * @param meta meta data associated with the URI
- * @param client_info client info pointer to use for associated events
- * @param anonymity anonymity level to use for the probes
- * @return the search result handle to access the probe activity
- */
- struct GNUNET_FS_SearchResult *
- GNUNET_FS_probe (struct GNUNET_FS_Handle *h,
- const struct GNUNET_FS_Uri *uri,
- const struct GNUNET_CONTAINER_MetaData *meta,
- void *client_info,
- uint32_t anonymity);
- /**
- * Stop probe activity. Must ONLY be used on values
- * returned from #GNUNET_FS_probe.
- *
- * @param sr search result to stop probing for (freed)
- * @return the value of the 'client_info' pointer
- */
- void *
- GNUNET_FS_probe_stop (struct GNUNET_FS_SearchResult *sr);
- /**
- * Options for downloading. Compatible options
- * can be OR'ed together.
- */
- enum GNUNET_FS_DownloadOptions
- {
- /**
- * No options (use defaults for everything).
- */
- GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
- /**
- * Only download from the local host, do not access remote systems (no P2P)
- */
- GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1,
- /**
- * Do a recursive download (that is, automatically trigger the
- * download of files in directories).
- */
- GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2,
- /**
- * Do not append temporary data to
- * the target file (for the IBlocks).
- */
- GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4,
- /**
- * Internal option used to flag this download as a 'probe' for a
- * search result. Impacts the priority with which the download is
- * run and causes signalling callbacks to be done differently.
- * Also, probe downloads are not serialized on suspension. Normal
- * clients should not use this!
- */
- GNUNET_FS_DOWNLOAD_IS_PROBE = (1 << 31)
- };
- /**
- * Download parts of a file. Note that this will store
- * the blocks at the respective offset in the given file. Also, the
- * download is still using the blocking of the underlying FS
- * encoding. As a result, the download may *write* outside of the
- * given boundaries (if offset and length do not match the 32k FS
- * block boundaries).
- *
- * The given range can be used to focus a download towards a
- * particular portion of the file (optimization), not to strictly
- * limit the download to exactly those bytes.
- *
- * @param h handle to the file sharing subsystem
- * @param uri the URI of the file (determines what to download); CHK or LOC URI
- * @param meta known metadata for the file (can be NULL)
- * @param filename where to store the file, maybe NULL (then no file is
- * created on disk and data must be grabbed from the callbacks)
- * @param tempname where to store temporary file data, not used if filename is non-NULL;
- * can be NULL (in which case we will pick a name if needed); the temporary file
- * may already exist, in which case we will try to use the data that is there and
- * if it is not what is desired, will overwrite it
- * @param offset at what offset should we start the download (typically 0)
- * @param length how many bytes should be downloaded starting at offset
- * @param anonymity anonymity level to use for the download
- * @param options various download options
- * @param cctx initial value for the client context for this download
- * @param parent parent download to associate this download with (use NULL
- * for top-level downloads; useful for manually-triggered recursive downloads)
- * @return context that can be used to control this download
- */
- struct GNUNET_FS_DownloadContext *
- GNUNET_FS_download_start (struct GNUNET_FS_Handle *h,
- const struct GNUNET_FS_Uri *uri,
- const struct GNUNET_CONTAINER_MetaData *meta,
- const char *filename, const char *tempname,
- uint64_t offset, uint64_t length, uint32_t anonymity,
- enum GNUNET_FS_DownloadOptions options, void *cctx,
- struct GNUNET_FS_DownloadContext *parent);
- /**
- * Download parts of a file based on a search result. The download
- * will be associated with the search result (and the association
- * will be preserved when serializing/deserializing the state).
- * If the search is stopped, the download will not be aborted but
- * be 'promoted' to a stand-alone download.
- *
- * As with the other download function, this will store
- * the blocks at the respective offset in the given file. Also, the
- * download is still using the blocking of the underlying FS
- * encoding. As a result, the download may *write* outside of the
- * given boundaries (if offset and length do not match the 32k FS
- * block boundaries).
- *
- * The given range can be used to focus a download towards a
- * particular portion of the file (optimization), not to strictly
- * limit the download to exactly those bytes.
- *
- * @param h handle to the file sharing subsystem
- * @param sr the search result to use for the download (determines uri and
- * meta data and associations)
- * @param filename where to store the file, maybe NULL (then no file is
- * created on disk and data must be grabbed from the callbacks)
- * @param tempname where to store temporary file data, not used if filename is non-NULL;
- * can be NULL (in which case we will pick a name if needed); the temporary file
- * may already exist, in which case we will try to use the data that is there and
- * if it is not what is desired, will overwrite it
- * @param offset at what offset should we start the download (typically 0)
- * @param length how many bytes should be downloaded starting at offset
- * @param anonymity anonymity level to use for the download
- * @param options various download options
- * @param cctx initial value for the client context for this download
- * @return context that can be used to control this download
- */
- struct GNUNET_FS_DownloadContext *
- GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h,
- struct GNUNET_FS_SearchResult *sr,
- const char *filename,
- const char *tempname, uint64_t offset,
- uint64_t length, uint32_t anonymity,
- enum GNUNET_FS_DownloadOptions options,
- void *cctx);
- /**
- * Stop a download (aborts if download is incomplete).
- *
- * @param dc handle for the download
- * @param do_delete delete files of incomplete downloads
- */
- void
- GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete);
- /**
- * Suspend a download.
- *
- * @param dc handle for the download
- */
- void
- GNUNET_FS_download_suspend (struct GNUNET_FS_DownloadContext *dc);
- /**
- * Resume a suspended download.
- *
- * @param dc handle for the download
- */
- void
- GNUNET_FS_download_resume (struct GNUNET_FS_DownloadContext *dc);
- /* ******************** Directory API *********************** */
- #define GNUNET_FS_DIRECTORY_MIME "application/gnunet-directory"
- #define GNUNET_FS_DIRECTORY_MAGIC "\211GND\r\n\032\n"
- #define GNUNET_FS_DIRECTORY_EXT ".gnd"
- /**
- * Does the meta-data claim that this is a directory?
- * Checks if the mime-type is that of a GNUnet directory.
- *
- * @return #GNUNET_YES if it is, #GNUNET_NO if it is not, #GNUNET_SYSERR if
- * we have no mime-type information (treat as #GNUNET_NO)
- */
- int
- GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData
- *md);
- /**
- * Set the MIMETYPE information for the given
- * metadata to "application/gnunet-directory".
- *
- * @param md metadata to add mimetype to
- */
- void
- GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
- /**
- * Suggest a filename based on given metadata.
- *
- * @param md given meta data
- * @return NULL if meta data is useless for suggesting a filename
- */
- char *
- GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData *md);
- /**
- * Function used to process entries in a directory.
- *
- * @param cls closure
- * @param filename name of the file in the directory
- * @param uri URI of the file
- * @param metadata metadata for the file; metadata for
- * the directory if everything else is NULL/zero
- * @param length length of the available data for the file
- * (of type size_t since data must certainly fit
- * into memory; if files are larger than size_t
- * permits, then they will certainly not be
- * embedded with the directory itself).
- * @param data data available for the file (length bytes)
- */
- typedef void (*GNUNET_FS_DirectoryEntryProcessor) (void *cls,
- const char *filename,
- const struct GNUNET_FS_Uri *
- uri,
- const struct
- GNUNET_CONTAINER_MetaData *
- meta, size_t length,
- const void *data);
- /**
- * Iterate over all entries in a directory. Note that directories
- * are structured such that it is possible to iterate over the
- * individual blocks as well as over the entire directory. Thus
- * a client can call this function on the buffer in the
- * GNUNET_FS_ProgressCallback. Also, directories can optionally
- * include the contents of (small) files embedded in the directory
- * itself; for those files, the processor may be given the
- * contents of the file directly by this function.
- *
- * @param size number of bytes in data
- * @param data pointer to the beginning of the directory
- * @param offset offset of data in the directory
- * @param dep function to call on each entry
- * @param dep_cls closure for @a dep
- * @return #GNUNET_OK if this could be a block in a directory,
- * #GNUNET_NO if this could be part of a directory (but not 100% OK)
- * #GNUNET_SYSERR if 'data' does not represent a directory
- */
- int
- GNUNET_FS_directory_list_contents (size_t size, const void *data,
- uint64_t offset,
- GNUNET_FS_DirectoryEntryProcessor dep,
- void *dep_cls);
- /**
- * Opaque handle to a directory builder.
- */
- struct GNUNET_FS_DirectoryBuilder;
- /**
- * Create a directory builder.
- *
- * @param mdir metadata for the directory
- */
- struct GNUNET_FS_DirectoryBuilder *
- GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData
- *mdir);
- /**
- * Add an entry to a directory.
- *
- * @param bld directory to extend
- * @param uri uri of the entry (must not be a KSK)
- * @param md metadata of the entry
- * @param data raw data of the entry, can be NULL, otherwise
- * data must point to exactly the number of bytes specified
- * by the uri
- */
- void
- GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
- const struct GNUNET_FS_Uri *uri,
- const struct GNUNET_CONTAINER_MetaData *md,
- const void *data);
- /**
- * Finish building the directory. Frees the
- * builder context and returns the directory
- * in-memory.
- *
- * @param bld directory to finish
- * @param rsize set to the number of bytes needed
- * @param rdata set to the encoded directory
- * @return #GNUNET_OK on success
- */
- int
- GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
- size_t * rsize, void **rdata);
- /* ******************** DirScanner API *********************** */
- /**
- * Progress reasons of the directory scanner.
- */
- enum GNUNET_FS_DirScannerProgressUpdateReason
- {
- /**
- * We've started processing a file or directory.
- */
- GNUNET_FS_DIRSCANNER_FILE_START = 0,
- /**
- * We're having trouble accessing a file (soft-error); it will
- * be ignored.
- */
- GNUNET_FS_DIRSCANNER_FILE_IGNORED,
- /**
- * We've found all files (in the pre-pass).
- */
- GNUNET_FS_DIRSCANNER_ALL_COUNTED,
- /**
- * We've finished extracting meta data from a file.
- */
- GNUNET_FS_DIRSCANNER_EXTRACT_FINISHED,
- /**
- * Last call to the progress function: we have finished scanning
- * the directory.
- */
- GNUNET_FS_DIRSCANNER_FINISHED,
- /**
- * There was an internal error. Application should abort the scan.
- */
- GNUNET_FS_DIRSCANNER_INTERNAL_ERROR
- };
- /**
- * Function called over time as the directory scanner makes
- * progress on the job at hand.
- *
- * @param cls closure
- * @param filename which file we are making progress on
- * @param is_directory #GNUNET_YES if this is a directory,
- * #GNUNET_NO if this is a file
- * #GNUNET_SYSERR if it is neither (or unknown)
- * @param reason kind of progress we are making
- */
- typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
- const char *filename,
- int is_directory,
- enum GNUNET_FS_DirScannerProgressUpdateReason reason);
- /**
- * A node of a directory tree (produced by dirscanner)
- */
- struct GNUNET_FS_ShareTreeItem
- {
- /**
- * This is a doubly-linked list
- */
- struct GNUNET_FS_ShareTreeItem *prev;
- /**
- * This is a doubly-linked list
- */
- struct GNUNET_FS_ShareTreeItem *next;
- /**
- * This is a doubly-linked tree
- * NULL for top-level entries.
- */
- struct GNUNET_FS_ShareTreeItem *parent;
- /**
- * This is a doubly-linked tree
- * NULL for files and empty directories
- */
- struct GNUNET_FS_ShareTreeItem *children_head;
- /**
- * This is a doubly-linked tree
- * NULL for files and empty directories
- */
- struct GNUNET_FS_ShareTreeItem *children_tail;
- /**
- * Metadata for this file or directory
- */
- struct GNUNET_CONTAINER_MetaData *meta;
- /**
- * Keywords for this file or directory (derived from metadata).
- */
- struct GNUNET_FS_Uri *ksk_uri;
- /**
- * Name of the file/directory
- */
- char *filename;
- /**
- * Base name of the file/directory.
- */
- char *short_filename;
- /**
- * #GNUNET_YES if this is a directory
- */
- int is_directory;
- };
- /**
- * Opaque handle to an asynchronous directory scanning activity.
- */
- struct GNUNET_FS_DirScanner;
- /**
- * Start a directory scanner.
- *
- * @param filename name of the directory to scan
- * @param disable_extractor #GNUNET_YES to not run libextractor on files (only
- * build a tree)
- * @param ex if not NULL, must be a list of extra plugins for extractor
- * @param cb the callback to call when there are scanning progress messages
- * @param cb_cls closure for @a cb
- * @return directory scanner object to be used for controlling the scanner
- */
- struct GNUNET_FS_DirScanner *
- GNUNET_FS_directory_scan_start (const char *filename,
- int disable_extractor,
- const char *ex,
- GNUNET_FS_DirScannerProgressCallback cb,
- void *cb_cls);
- /**
- * Abort the scan. Must not be called from within the progress_callback
- * function.
- *
- * @param ds directory scanner structure
- */
- void
- GNUNET_FS_directory_scan_abort (struct GNUNET_FS_DirScanner *ds);
- /**
- * Obtain the result of the scan after the scan has signalled
- * completion. Must not be called prior to completion. The @a ds is
- * freed as part of this call.
- *
- * @param ds directory scanner structure
- * @return the results of the scan (a directory tree)
- */
- struct GNUNET_FS_ShareTreeItem *
- GNUNET_FS_directory_scan_get_result (struct GNUNET_FS_DirScanner *ds);
- /**
- * Process a share item tree, moving frequent keywords up and
- * copying frequent metadata up.
- *
- * @param toplevel toplevel directory in the tree, returned by the scanner
- */
- void
- GNUNET_FS_share_tree_trim (struct GNUNET_FS_ShareTreeItem *toplevel);
- /**
- * Release memory of a share item tree.
- *
- * @param toplevel toplevel of the tree to be freed
- */
- void
- GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel);
- #if 0 /* keep Emacsens' auto-indent happy */
- {
- #endif
- #ifdef __cplusplus
- }
- #endif
- #endif
- /** @} */ /* end of group */
|