実体は、HTTP のやりとりに関するすべての情報を格納する構造体だが、 プログラマはこの構造体へのポインタのみを扱い、実体はブラックボッ クスとして扱うべきである。 ghttp_request_new() で確保、 ghttp_request_destroy() で解放する。 情報の設定は、すべて、このライブラリに含まれる各種のサービス関数 を経由すること。
HTTP のリクエスト等の種類を規定する定数(enum)の型。 ghttp_set_type() の引数として使わ れる。取りうる値は以下にあげるいずれかの値。
ghttp_type_get /* GET メソッド */ ghttp_type_options /* OPTION メソッド */ ghttp_type_head /* HEAD メソッド */ ghttp_type_post /* POST メソッド */ ghttp_type_put /* PUT メソッド */ ghttp_type_delete /* DELETE メソッド */ ghttp_type_trace /* TRACE メソッド */ ghttp_type_connect /* CONNECT メソッド */ ghttp_type_propfind /* PROPFIND メソッド(WebDAV, RFC2518) */ ghttp_type_proppatch /* PROPPATCH メソッド(WebDAV, RFC2518) */ ghttp_type_mkcol /* MKCOL メソッド(WebDAV, RFC2518) */ ghttp_type_copy /* COPY メソッド(WebDAV, RFC2518) */ ghttp_type_move /* MOVE メソッド(WebDAV, RFC2518) */ ghttp_type_lock /* LOCK メソッド(WebDAV, RFC2518) */ ghttp_type_unlock /* UNLOCK メソッド(WebDAV, RFC2518) */
ghttp_process() を同期/非同期のど ちらのモードで動かすかを規定する定数(enum)の型。 ghttp_set_sync() の引数として用い る。取りうる値は以下のいずれかの値。
ghttp_sync /* 同期モード */ ghttp_async /* 非同期モード */
ghttp_process() の戻り値の定数 (enum)の型。取りうる値は以下のいずれかの値。
ghttp_error /* エラー */ ghttp_not_done /* 終了していない */ ghttp_done /* 終了 */
ghttp_current_status 型のメンバの定 数(enum)の型。取りうる値は以下のいずれかの値。
ghttp_proc_none /* プロセスなし */ ghttp_proc_request /* リクエスト中 */ ghttp_proc_response_hdrs /* ヘッダ受信中 */ ghttp_proc_response /* ボディ受信中 */
ghttp_get_status() の戻り値の構造 体の型。構造体のメンバは、以下のもの。
ghttp_proc proc; /* 何をしているか */ int bytes_read; /* すでに読んだバイト数 */ int bytes_total; /* 全体のバイト数 */
ghttp_request * ghttp_request_new(void)
ghttp_request_new() は、request オ ブジェクトを新たに生成する。
新たに確保した ghttp_request へのポ インタを返す。確保に失敗した場合は、NULL が返るかもしれないし、 返れずにセグメンテーション違反を起こすかもしれない。
関数内部のメモリ確保操作後、チェックなしにオブジェクト内にアクセ スしているため、メモリ確保に失敗した場合、セグメンテーション違反 を起こす可能性が高い。
void ghttp_request_destroy( ghttp_request *a_request)
ghttp_request_destroy() は、 a_request が占有していた資源を解放する。
なし。
たぶん、問題ない。が、資源の解放の成否をチェックしていないので、 解放失敗等を検出することはできない。
int ghttp_uri_validate( char *a_uri)
ghttp_uri_validate() は、 a_uri を評価し、URI として解釈可能か検査する。
正常の場合は 0。異常がある場合は -1 を返す。
たぶん、問題ない。が、異常の理由は教えてくれない。また、0 が返っ たからと言って、 RFC2396 にてらしてまったく問題がないとも言えない気がする。
int ghttp_set_uri( ghttp_request *a_request, char *a_uri)
ghttp_set_uri() は、 a_uri を、a_request がリクエストする URI として設定する。
正常の場合は 0。異常がある場合は -1 を返す。
ghttp_uri_validate() と同じ URI の 構文チェックをするので、同じ問題を持っている。また、内部で使用す るメモリの確保チェックを行っていない部分があるので、メモリ確保に 失敗した場合、セグメンテーション違反を発生する可能性がある。
int ghttp_set_proxy( ghttp_request *a_request, char *a_uri)
ghttp_set_proxy() は、 a_uri を、a_request が使用する http proxy の URI として設定する。
正常の場合は 0。異常がある場合は -1 を返す。
ghttp_set_uri() と同じ問題を持って いる。また、同じ a_request に対して何回も呼び出すとメ モリリークを発生するので、1回しか呼び出さないことを推奨する。
int ghttp_set_type( ghttp_request *a_request, ghttp_type a_type)
ghttp_set_type() は、 a_request が使用するメソッドを a_type に 設定する。
正常の場合は 0。未定義のメソッドの場合は -1 を返す。
たぶん、ない。
int ghttp_set_body( ghttp_request *a_request, char *a_body, int a_len)
ghttp_set_body() は、 リクエストボディとして、長さ a_len の a_body を a_request に設定する。 a_body をそのままリクエストボディとして使うので、 a_body の指すメモリはリクエスト終了まで保持すること。 また、そのメモリ領域は、プログラマの責任で確保・解放すること。
正常の場合は 0。メソッドが POST, PUT, PROPPATCH, PROPFIND, LOCK 以外の場合は -1 を返す。
たぶん、ない。
int ghttp_set_sync( ghttp_request *a_request, ghttp_sync_mode a_mode)
ghttp_set_sync() は、 リクエストの実行時に、同期モード、非同期モードのどちらを使うか設 定する。
正常の場合は 0。a_mode が、ghttp_sync または ghttp_async 以外の場合は -1 を返す。
たぶん、ない。
int ghttp_prepare( ghttp_request *a_request)
ghttp_prepare() は、 リクエストの実行の準備として、必要なパラメータが設定されているこ とと、設定されたパラメータに対応したリクエストヘッダの生成等を行 う。なお、proxy を経由しない場合は、http 以外の URI scheme は許 可しない。
正常の場合は 0。異常の場合は -1 を返す。
たぶん、ない。ただし、異常の理由を知る手段はない。
void ghttp_set_chunksize( ghttp_request *a_request, int a_size)
ghttp_set_chunksize() は、リクエス ト実行用のI/O バッファのサイズを設定する。回線速度が異なる場合に、 バッファサイズを変更して最適化することもできなくはない。
なお、a_size が 0 以下の場合は、バッファサイズは変更 されない。
なし。
たぶん、ない。
void ghttp_set_header( ghttp_request *a_request, const char *a_hdr, const char *a_val)
ghttp_set_header() は、既知のヘッ ダ(a_hdr)に対し、値を a_val に設定する。
サポートされているヘッダは以下のものである。
http_hdr_Allow /* Allow: */ http_hdr_Content_Encoding /* Content-Encoding: */ http_hdr_Content_Language /* Content-Language: */ http_hdr_Content_Length /* Content-Length: */ http_hdr_Content_Location /* Content-Location: */ http_hdr_Content_MD5 /* Content-MD5: */ http_hdr_Content_Range /* Content-Range: */ http_hdr_Content_Type /* Content-Type: */ http_hdr_Expires /* Expires: */ http_hdr_Last_Modified /* Last-Modified: */ http_hdr_Cache_Control /* Cache-Control: */ http_hdr_Connection /* Connection: */ http_hdr_Date /* Date: */ http_hdr_Pragma /* Pragma: */ http_hdr_Transfer_Encoding /* Transfer-Encoding: */ http_hdr_Upgrade /* Upgrade: */ http_hdr_Trailer /* Trailer: */ http_hdr_Via /* Via: */ /* リクエストヘッダのみ */ http_hdr_Accept /* Accept: */ http_hdr_Accept_Charset /* Accept-Charset */ http_hdr_Accept_Encoding /* Accept-Encodeing */ http_hdr_Accept_Language /* Accept-Language */ http_hdr_Authorization /* Authorization: */ http_hdr_Expect /* Expect: */ http_hdr_From /* From: */ http_hdr_Host /* Host: */ http_hdr_If_Modified_Since /* If-Modified-Since: */ http_hdr_If_Match /* If-Match: */ http_hdr_If_None_Match /* If-None-Match: */ http_hdr_If_Range /* If-Range: */ http_hdr_If_Unmodified_Since /* If-Unmodified-Since */ http_hdr_Max_Forwards /* Max-Forwards: */ http_hdr_Proxy_Authorization /* Proxy-Authorization: */ http_hdr_Range /* Range */ http_hdr_Referer /* Referer: */ http_hdr_TE /* TE: */ http_hdr_User_Agent /* User-Agent: */ /* レスポンスヘッダのみ */ http_hdr_Accept_Ranges /* Accept-Ranges: */ http_hdr_Age /* Age: */ http_hdr_ETag /* ETag: */ http_hdr_Location /* Location: */ http_hdr_Retry_After /* Retry-After: */ http_hdr_Server /* Server: */ http_hdr_Vary /* Vary: */ http_hdr_Warning /* Warning: */ http_hdr_WWW_Authenticate /* WWW-Authenticate: */
なし。ただし、未知のヘッダを指定した場合は設定されない。
レスポンスヘッダ専用のヘッダに対しても値を設定できてしまう(実害 はない)。配布物のままでは、一部、ヘッダ名称に誤りがあるので、 libghttp-1.0.9-headername.patch により修正することを推奨する。
ghttp_status ghttp_process( ghttp_request *a_request)
ghttp_process() は、 リクエストを発行し、サーバからの応答を取得する。非同期モードの場 合の動作は未解明。
正常で転送が終了したとき ghttp_done、非同期モードで転送が終了し ていないとき ghttp_not_done、異常のとき ghttp_error。
ないことを期待。
ghttp_current_status ghttp_get_status( ghttp_request *a_request)
ghttp_get_status() は、 リクエストの現在の状態を取得し、 ghttp_current_status 型の構造体とし て返す。
ghttp_current_status 型の構造体に格 納される。
a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。
void ghttp_flush_response_buffer( ghttp_request *a_request)
ghttp_flush_response_buffer() は、 a_request の I/O バッファから取得したデータをレスポン スボディへ押し出す。これにより、非同期モードの場合、データ取得の 途中でもデータを取り出すことができるようになる。
なし。
a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。
char * ghttp_get_header( ghttp_request *a_request, const char *a_hdr)
ghttp_get_header() は、 a_hdr で指定されるレスポンスヘッダの値を取得する。 a_hdr の指定には、 ghttp_set_header() の項目にある、 ヘッダ名称の変数を使用すること。
正常の場合、対応するレスポンスヘッダの値へのポインタ。ただし、ヘッ ダの値を保持するメモリ領域へのポインタが返るので、参照先のメモリ 上の値を変更してはならない。異常の場合は NULL を返す。
a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。
int ghttp_get_header_names( ghttp_request *a_request, char ***a_hdrs, int *a_num_hdrs)
ghttp_get_header_names() は、 レスポンスヘッダとしてサーバから返されたヘッダの名称のリストを a_hdrs に、戻されたヘッダの数を a_num_hdrs に設定する。a_hdrs の参照先は新 たに確保されるので、使用後は、プログラマの責任で解放すること。
正常の場合 0、異常の場合 -1 を返す。
a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。
int ghttp_close( ghttp_request *a_request)
ghttp_close() は、 実行中のリクエストを中断する。
正常の場合 0、異常の場合 -1 を返す。
socket の close の成否はチェックしないので、本当に close できた かどうかを確認する方法はない。
void ghttp_clean( ghttp_request *a_request)
ghttp_clean() は、 レスポンスの格納領域を再初期化する。
なし。
a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。
int ghttp_get_socket( ghttp_request *a_request)
ghttp_get_socket() は、 a_request に結びつけられた socket を取得する。
取得した socket。存在しない場合は -1 を返す。
たぶん、ない。
char * ghttp_get_body( ghttp_request *a_request)
ghttp_get_body() は、 エンティティボディを取得する。
取得したエンティティボディ。異常の場合は NULL を返す。
たぶん、ない。
int ghttp_get_body_len( ghttp_request *a_request)
ghttp_get_body_len() は、 エンティティボディの長さを取得する。
取得したエンティティボディの長さ。異常の場合は 0 を返す。
たぶん、ない。
char * ghttp_get_error( ghttp_request *a_request)
ghttp_get_error() は、 通信中に設定されたエラーメッセージを取得する。
設定されたエラーメッセージ。異常の場合やメッセージが設定されてい ない場合は NULL を返す。
たぶん、ない。
time_t ghttp_parse_date( char *a_date)
ghttp_parse_date() は、 RFC1123 の形式、ANSI C の形式、 RFC1036 の形式のいずれかの日付時刻文字列(a_date)をパースし、 1970年1月1日0時0分0秒からの通算秒に変換する。
変換された通算秒。異常の場合は、0 または -1 を返す。
たぶん、ない。でも、a_date が NULL のときに 0 を返し ているのはバグっぽい。また、タイムゾーンが GMT 以外だと使えない かもしれない。
int ghttp_status_code( ghttp_request *a_request)
ghttp_status_code() は、 リクエストの実行結果のステータスコードを取得する。
取得したステータスコード。異常の場合は、0 を返す。
たぶん、ない。
const char * ghttp_reason_phrase( ghttp_request *a_request)
ghttp_reason_phrase() は、 リクエストの実行結果の Reason-Phrase (ステータスコードに対応し た文字列で、例えば、200 に対して "OK", 404 に対して "Not Found" など)を取得する。
取得した Reason-Phrase。異常の場合は、NULL を返す。
たぶん、ない。
int ghttp_set_authinfo( ghttp_request *a_request, const char *a_user, const char *a_pass)
ghttp_set_authinfo() は、 ユーザ名(a_user)、パスワード(a_pass)の組を a_request に設定する。
0。異常の場合は、-1 を返す。
メモリ確保周りのチェックが不十分なため、メモリ確保に失敗した場合、 セグメンテーション違反を起こす可能性が高い。
int ghttp_set_proxy_authinfo( ghttp_request *a_request, const char *a_user, const char *a_pass)
ghttp_set_proxy_authinfo() は、 proxy 用のユーザ名(a_user)、 パスワード(a_pass)の組を a_request に設定する。
0。異常の場合は、-1 を返す。
メモリ確保周りのチェックが不十分なため、メモリ確保に失敗した場合、 セグメンテーション違反を起こす可能性が高い。