// 疑似コードによるマニュアル

/**
 * HttpRequestクラス
 * @description HTTP/HTTPS による非同期通信機能を提供します。
 * ファイルの送受信処理はバックグラウンド実行されます。
 */
class HttpRequest {

	/**
	 * コンストラクタ
	 * @param window スレッド同期処理用親ウインドウ
	 * @param cert HTTP通信時に証明書チェックを行うかどうか。falseにすると強制許可になります。
	 * @param agentName HTTP通信時のエージェント名
	 * @throw InvalidObject 親ウインドウ指定が不正
	 */
	function HttpRequest(window, cert=true, agentName="KIRIKIRI");

	/**
	 * 指定したメソッドで指定URLにリクエストする
	 * @description ※常に非同期での呼び出しになります
	 * @param method アクセスメソッド
	 * @param url リクエスト先のURL
	 * @param userName ユーザ名。指定すると認証ヘッダをつけます
	 * @param password パスワード
	 * @throw 通信エラーもろもろ（エラーメッセージ）
	 */
	function open(method, url, userName=void, password=void);

	/**
	 * 送信時に送られるヘッダーを追加する
	 * @param name ヘッダ名
	 * @param value 値
	 * @throw "already running" 既に送信中
	 * Content-Type を指定した場合は指定したエンコードが send 時の規定のエンコードになります。
	 */
	function setRequestHeader(name, value);

	/**
	 * リクエストの送信。送信処理は非同期実行されます。
	 * @description エラー時も例外は発生しませんので、readyState と status で判定してください。
	 * @param data 送信するデータ
	 * octetの場合  : そのまま送信
	 * 文字列の場合 : 規定のエンコードで処理して送信
	 * その他       : データは送信されません
	 * @param storeStrorage レスポンス保存先ファイル。指定された場合はプロパティ responseは 設定されません
	 * @throw "not open" openされていない
	 * @throw "already running" 既に送信中
	 * @throw "saveStorage open failed" 保存先ファイルが開けなかった場合
	 */
	function send(data=void, storeStorage=void);
	
	/**
	 * リクエストの送信。送受信は非同期実行されます。
	 * @description エラー時も例外は発生しませんので、readyState と status で判定してください。
	 * @param storage 送信するファイルデータ
	 * @param storeStrorage レスポンス保存先ファイル。指定された場合はプロパティ responseは 設定されません
	 * @throw "not open" openされていない
	 * @throw "already running" 既に送信中
	 * @throw "sendStorage open failed" 送信ファイルが開けなかった場合
	 * @throw "saveStorage open failed" 保存先ファイルが開けなかった場合
	 */
	function sendStorage(storage, storeStorage=void);
	
	/**
	 * 現在実行中の送受信のキャンセル
	 */
	function abort();

	/**
	 * すべての HTTPヘッダを取得する
	 * @return HTTPヘッダが格納された辞書
	 */
	function getAllResponseHeaders();

	/**
	 * 指定したHTTPヘッダを取得する
	 * @param name ヘッダラベル名
	 * @return ヘッダの値
	 */
	function getResponseHeader(name);

	/**
	 * レスポンスをテキストの形で取得
	 * @param encoding エンコード指定。省略時は Content-type の指定に従います。
	 */
	function getResponseText(encoding=void);

	// readyState 初期状態
	const UNINITIALIZED = 0;
	// readyState 処理開始
	const OPEN = 1;
	// readyState リクエスト送信
	const SENT = 2;
	// readyState 受信中
	const RECEIVING = 3;
	// readyState 読み込み完了
	const LOADED = 4;
	
	/**
	 * 通信状態。読み込み専用
	 * @return 現在の通信状態
	 */
	property readyState;

	/**
	 * レスポンス。読み込み専用。
	 * @return レスポンスデータ
	 * ContentType が text の場合：エンコード指定で変換された文字列が帰ります
	 * その他 : octet データそのまま
	 */
	property response;
	
	/**
	 * レスポンス｡読み込み専用
	 * @return レスポンスデータ(octet)
	 */
	property responseData;
	
	/**
	 * レスポンスの HTTPステータスコード。読み込み専用
	 * @return ステータスコード -1:キャンセル 0:通信エラー その他:httpステータスコード
	 */
	property status;
	
	/**
	 * レスポンスの HTTPステータスの文字列
	 * @return レスポンス文字列。通信エラー時はそのエラーメッセージになります。
	 */
	property statusText;

	/**
	 * レスポンスの Content-Type (エンコーディング指定は含まない)
	 */
	property contentType;

	/**
	 * レスポンスの Content-Type のエンコード指定
	 * @description ヘッダの指定が優先されますが、未指定、かつ受信データが text/html の場合は
	 * ファイル冒頭にある META 指定も参照します。
	 */
	property contentTypeEncoding;

	/**
	 * レスポンスの Content-Length
	 * @description ヘッダに無い場合はファイルダウンロード完了後にサイズ確定します。
	 */
	property contentLength;
	
	// ------------------------------------
	// イベント
	// ------------------------------------

	/**
	 * readyState が変化した場合のイベント
	 * @param readyState 新しいステート
	 */
	function onReadyStateChange(readyState);

	/**
	 * データ送受信イベント
	 * @param upload 送信中は true
	 * @param percent 進捗状態(0〜100%)
	 */
	function onProgress(upload, percent);
};
