(* 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
open Hlfreenet

(* Type for all callbacks (which have single parameters) *)
type 'a action_result =
    Result of 'a
  | Error of exn

(* This is the class type for node_async, and defines its *)
(* interface. *) 
class type node_async_type =
  object

(* Get the maximum number of simultaneous asynchronous actions. *)
    method actions_max : int

(* Get the maximum number of splitfile request threads for a single *)
(* action. *)
    method splitfile_threads_max : int

(* Get the maximum number of bytes to be read from a stream at *)
(* once. *)
    method block_len : int

(* Get the maximum number of request or insert attempts before *)
(* giving up. *)
    method attempts_max : int

(* Get the factor by which the HTL for a request is multipled in *)
(* response to a DataNotFound message. *)
    method dnf_retry_htl_mult : float

(* Get the attempted splitfile block length in bytes for splitfile *)
(* insertion. *)
    method splitfile_block_len_try : int

(* Set the maximum number of simultaneous asynchronous actions. *)
    method set_actions_max : int -> unit

(* Set the maximum number of splitfile request threads for a single *)
(* action. *)
    method set_splitfile_threads_max : int -> unit

(* Set the maximum number of bytes to be read from a stream at *)
(* once. *)
    method set_block_len : int -> unit

(* Set the maximum number of request or insert attempts before *)
(* giving up. *)
    method set_attempts_max : int -> unit

(* Set the factor by which the HTL for a request is multipled in *)
(* response to a DataNotFound message. *)
    method set_dnf_retry_htl_mult : float -> unit

(* Set the attempted splitfile block length in bytes for splitfile *)
(* insertion. *)
    method set_splitfile_block_len_try : int -> unit

(* Get the current number of asynchronous actions. *)
    method actions : int

(* Wait for all asynchronous actions to complete. *)
    method wait_all : unit

(* Do an asynchronous high level request, and call a callback in a *)
(* new thread once it is complete with the requested file's *)
(* metadata. *)
    method request : callback:(fieldset action_result -> unit) ->
      uri:string -> htl:int -> stream:fstream_out -> unit

(* Do an asynchronous high level request, and call a callback in a *)
(* new thread once it is complete with the requested file's control *)
(* datastructure and info metadata pair; do not follow control *)
(* metadata. *)
    method request_control_info :
	callback:(control_info action_result -> unit) -> uri:string ->
	  htl:int -> unit

(* Do an asynchronous high level request, and call a callback in a *)
(* new thread once it is complete with the requested file's map *)
(* datastructure; do not follow control metadata. *)
    method request_map : callback:(map action_result -> unit) ->
      uri:string -> htl:int -> unit

(* Do an asynchronous high level insert of a file with a map *)
(* datastructure, and call a callback in a new thread once it is *)
(* complete with the inserted file's actual URI. *)
    method insert : callback:(string action_result -> unit) ->
      uri:string -> htl:int -> map:map -> stream:fstream_in -> unit

(* Do an asynchronous high level insert of a file with a control *)
(* datastructure and info metadata pair, and call a callback in a *)
(* new thread once it is complete with the inserted file's actual*)
(* URI. *)
    method insert_no_map : callback:(string action_result -> unit) ->
      uri:string -> htl:int -> control_info:control_info ->
	stream:fstream_in -> unit

(* Do an asynchronous high level insert of a file with only info *)
(* metadata, and call a callback in a new thread once it is *)
(* complete with the inserted file's actual URI. *)
    method insert_info : callback:(string action_result -> unit) ->
      uri:string -> htl:int -> info:fieldset -> stream:fstream_in ->
	unit

(* Do an asynchronous high level insert of a file as a CHK with a *)
(* map datastructure, and call a callback in a new thread once it *)
(* is complete with the inserted file's actual URI. *)
    method insert_chk : callback:(string action_result -> unit) ->
      htl:int -> map:map -> stream:fstream_in -> unit

(* Do an asynchronous high level insert of a file as a CHK with a *)
(* control datastructure and info metadata pair, and call a *)
(* callback in a new thread once it is complete with the inserted *)
(* file's actual URI. *)
    method insert_chk_no_map : callback:(string action_result -> unit)
      -> htl:int -> control_info:control_info -> stream:fstream_in ->
	unit

(* Do an asynchronous high level insert of a file as a CHK with *)
(* onlyb info metadata, and call a callback in a new thread once it *)
(* is complete with the inserted file's actual URI. *)
    method insert_chk_info : callback:(string action_result -> unit)
      -> htl:int -> info:fieldset -> stream:fstream_in -> unit

(* Do an asynchronous high level insert of a file as a group of *)
(* splitfile blocks, and call a callback in a new thread once it *)
(* is complete with the resulting splitfile datastructure. *)
    method insert_splitfile_blocks :
	callback:(control_split_file action_result -> unit) -> htl:int
	  -> stream:fstream_in -> unit

(* Do an asynchronous high level insert of a file as a splitfile *)
(* and insert the resulting splitfile control metadata and info *)
(* metadata at a specified URI, and call a callback in a new thread *)
(* once it is complete with the real inserted URI. *)
    method insert_splitfile : callback:(string action_result -> unit)
      -> uri:string -> htl:int -> info:fieldset -> stream:fstream_in
	-> unit

(* Do an asynchronous high level insert of a file as a splitfile *)
(* and insert the resulting splitfile control metadata and info *)
(* metadata in a CHK, and call a callback in a new thread once it *)
(* is complete with the real inserted URI. *)
    method insert_splitfile_chk :
	callback:(string action_result -> unit) -> htl:int ->
	  info:fieldset -> stream:fstream_in -> unit

(* Do an asynchronous high level CHK generation from a stream with *)
(* a map datastructure. *)
    method generate_chk : callback:(string action_result -> unit) ->
      map:map -> stream:fstream_in -> unit

(* Do an asynchronous high level CHK generation from a stream with *)
(* a control datastructure and info metadata pair. *)
    method generate_chk_no_map :
	callback:(string action_result -> unit) ->
	  control_info:control_info -> stream:fstream_in -> unit

(* Do an asynchronous high level CHK generation from a stream with *)
(* info metadata. *)
    method generate_chk_info : callback:(string action_result -> unit)
      -> info:fieldset -> stream:fstream_in -> unit

(* Do an asynchronous SVK private-public key pair generation, where *)
(* the first item of the tuple returned is the private key and the *)
(* second item of the tupble returned is the public key. *)
    method generate_svk :
        callback:((string * string) action_result -> unit) -> unit
  end

(* This class forms a general multithreaded, asynchronous node *)
(* interface; note that it encapsulates Hlfreenet, and that *)
(* Hlfreenet handles splitfile request and insert multithreading. *)
class node_async : addr:string -> port:int -> actions_max:int ->
  splitfile_threads_max:int -> block_len:int -> attempts_max:int ->
    dnf_retry_htl_mult:float -> splitfile_block_len_try:int ->
      node_async_type