(* O'Caml high level Freenet client module                          *)
(* by Travis Bemann                                                 *)
(*                                                                  *)
(* This program is free software; you can redistribute it and/or    *)
(* modify it under the terms of the GNU Lesser General Public       *)
(* License as published by the Free Software Foundation; either     *)
(* version 2 of the License, or (at your option) any later version. *)
(*                                                                  *)
(* This program 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 Lesser General Public License for more details.              *)

open Fieldset
open Fstream

(* Every error condition you can think of *)
exception Bad_control of string
exception Future_dbr
exception Part_not_found of string
exception Default_not_found
exception Insert_map_part_uri
exception Bad_map_control

(* Control metadata representation datastructures *)
type control_date_redirect =
    { dbr_target : string;
      dbr_offset : int;
      dbr_increment : int }
      
type control_split_file =
    { spl_length : int;
      spl_blocks : string list;
      spl_blocks_check : string list }
      
type control =
    Redirect of string
  | Date_redirect of control_date_redirect
  | Split_file of control_split_file
  | No_control
      
(* Map(file) metadata representation datastructures *)
type control_info = control * fieldset
      
type map =
    { map_items : (string, control_info) Hashtbl.t;
      map_default : string option }

(* Create a map datastructre from a name and control datastructure *)
(* and info metadata pair association list with a default *)
val make_map : (string * control_info) list -> string option -> map

(* Convert a map into raw metadata *)
val metadata_raw_of_map : map -> string

(* Convert raw metadata into a map *)
val map_of_metadata_raw : string -> map

(* Generate DBR URI from URI and time after offset (in seconds) *)
val generate_dbr_uri : uri:string -> item:int -> string
  
(* Generate DBR URI from URI, time increment (in seconds), and *)
(* index (in increments) *)
val generate_dbr_uri_item : uri:string -> increment:int ->
  index:int -> string
  
(* Generate DBR URI from URI, offset (in seconds), time increment *)
(* (in seconds), and index (in increments) *)
val generate_dbr_uri_relative : uri:string -> offset:int ->
  increment:int -> index:int -> string
  
(* Generate DBR URI for next increment from URI, offset (in *)
(* seconds), and time increment (in seconds) *)
val generate_dbr_uri_next : uri:string -> offset:int ->
  increment:int -> string

(* A high level node, with specified address, port, maximum number *)
(* of threads, read block length, maximum number of attempts, *)
(* DataNotFound HTL multiplier, and attempted splitfile block *)
(* length. *)
class node_hl : addr:string -> port:int -> threads_max:int ->
  block_len:int -> attempts_max:int -> dnf_retry_htl_mult:float ->
    splitfile_block_len_try:int ->
      object ('a)
	
(* Get maximum number of simultaneously executing threads in *)
(* addition to a calling  thread. *)
	method threads_max : int

(* Get the size of individual blocks that are sent during *)
(* insertion. *)
	method block_len : int

(* Get the maximum number of attempts for an individual request or *)
(* insert. *)
	method attempts_max : int

(* Get the factor by which a request HTL is multiplied when retrying *)
(* a request that resulted in a DataNotFound response. *)
	method dnf_retry_htl_mult : float

(* Get the wanted splitfile block size; note that attempted is the *)
(* key thing here as it is automatically changed to make it a power *)
(* of two for the sake of efficiency (as all files within Freenet *)
(* are stored in units that are powers of two in size. *)
	method splitfile_block_len_try : int

(* Create a CHK generation transaction. *)
	method generate_chk : metadata_len:int -> data_len:int ->
	  Fcp.gen_chk_transact
	    
(* Create an SVK pair (private, public) - NOT an SVK pair *)
(* generation transaction, although one of these is used in the *)
(* implementation of this method. *)
	method generate_svk : string * string
    
(* Create a request transaction from a URI and a hops to live value *)
	method request : uri:string -> htl:int -> Fcp.request_transact

(* Create an insert transaction from a URI and a hops to live value *)
	method insert : uri:string -> htl:int -> metadata_len:int ->
	  data_len:int -> Fcp.insert_transact

(* Do a high level request, return the resulting info metadata. *)
	method request_hl : uri:string -> htl:int -> 
	  stream:fstream_out -> fieldset

(* Do a high level request, return the resulting control *)
(* datastructure and info metadata pair; do not follow control*)
(* metadata. *)
	method request_hl_control_info : uri:string -> htl:int ->
	  control_info

(* Do a high level request, return the following map; do not follow *)
(* control metadata. *)
	method request_hl_map : uri:string -> htl:int -> map

(* Do a high level insert of a file with a map datastructure. *)
	method insert_hl : uri:string -> htl:int -> map:map ->
	  stream:fstream_in -> string

(* Do a high level insert of a file with a control datastructure *)
(* and info metadata pair. *)
	method insert_hl_no_map : uri:string -> htl:int ->
	  control_info:control_info -> stream:fstream_in -> string

(* Do a high level insert of a file with info metadata. *)
	method insert_hl_info : uri:string -> htl:int -> info:fieldset
	  -> stream:fstream_in -> string

(* Do a high level insert of a file as a CHK with a map *)
(* datastructure, while catching Fcp.Key_collision so it is *)
(* ignored. *)
	method insert_hl_chk : htl:int -> map:map -> stream:fstream_in
	  -> string

(* Do a high level insert of a file as a CHK with a control *)
(* datastructure and info metadata pair, while catching *)
(* Fcp.Key_collision so it is ignored. *)
	method insert_hl_chk_no_map : htl:int ->
	  control_info:control_info -> stream:fstream_in -> string

(* Do a high level insert of a file as a CHK with info metadata, *)
(* while catching Fcp.Key_collision so it is ignored. *)
	method insert_hl_chk_info : htl:int -> info:fieldset ->
	  stream:fstream_in -> string

(* Do a high level insert of a file as a group of splitfile blocks *)
(* and return the resulting splitfile datastructure. *)
	method insert_hl_splitfile_blocks : htl:int ->
	  stream:fstream_in -> control_split_file

(* Do a high level insert of a file as a splitfile and insert the *)
(* corresponding splitfile control metadata and info metadata at *)
(* a specified URI. *)
	method insert_hl_splitfile : uri:string -> htl:int ->
	  info:fieldset -> stream:fstream_in -> string

(* Do a high level insert of a file as a splitfile in a CHK and *)
(* insert the corresponding splitfile control metadata and info *)
(* metadata at a specified URI, while catching Fcp.Key_collision *)
(* so it is ignored. *)
	method insert_hl_splitfile_chk : htl:int -> info:fieldset ->
	  stream:fstream_in -> string

(* Do a high level CHK generation from a stream and map *)
(* datastructure. *)
	method generate_chk_hl : map:map -> stream:fstream_in ->
	  string

(* Do a high level CHK generation from a stream and control *)
(* datastructure and info metadata pair. *)
	method generate_chk_hl_no_map : control_info:control_info ->
	  stream:fstream_in -> string

(* Do a high level CHK generation from a stream and info metadata. *)
	method generate_chk_hl_info : info:fieldset ->
	  stream:fstream_in -> string
      end