関数レファレンス

構造体・型

ghttp_request

実体は、HTTP のやりとりに関するすべての情報を格納する構造体だが、 プログラマはこの構造体へのポインタのみを扱い、実体はブラックボッ クスとして扱うべきである。 ghttp_request_new() で確保、 ghttp_request_destroy() で解放する。 情報の設定は、すべて、このライブラリに含まれる各種のサービス関数 を経由すること。

ghttp_type

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_sync_mode

ghttp_process() を同期/非同期のど ちらのモードで動かすかを規定する定数(enum)の型。 ghttp_set_sync() の引数として用い る。取りうる値は以下のいずれかの値。

  ghttp_sync             /* 同期モード */
  ghttp_async            /* 非同期モード */
ghttp_status

ghttp_process() の戻り値の定数 (enum)の型。取りうる値は以下のいずれかの値。

  ghttp_error            /* エラー */
  ghttp_not_done         /* 終了していない */
  ghttp_done             /* 終了 */
ghttp_proc

ghttp_current_status 型のメンバの定 数(enum)の型。取りうる値は以下のいずれかの値。

  ghttp_proc_none          /* プロセスなし */
  ghttp_proc_request       /* リクエスト中 */
  ghttp_proc_response_hdrs /* ヘッダ受信中 */
  ghttp_proc_response      /* ボディ受信中 */
ghttp_current_status

ghttp_get_status() の戻り値の構造 体の型。構造体のメンバは、以下のもの。

  ghttp_proc         proc;        /* 何をしているか */
  int                bytes_read;  /* すでに読んだバイト数 */
  int                bytes_total; /* 全体のバイト数 */

関数

ghttp_request_new()

書式

ghttp_request * ghttp_request_new(void)

説明

ghttp_request_new() は、request オ ブジェクトを新たに生成する。

戻り値

新たに確保した ghttp_request へのポ インタを返す。確保に失敗した場合は、NULL が返るかもしれないし、 返れずにセグメンテーション違反を起こすかもしれない。

バグ

関数内部のメモリ確保操作後、チェックなしにオブジェクト内にアクセ スしているため、メモリ確保に失敗した場合、セグメンテーション違反 を起こす可能性が高い。

ghttp_request_destroy()

書式

void ghttp_request_destroy( ghttp_request *a_request)

説明

ghttp_request_destroy() は、 a_request が占有していた資源を解放する。

戻り値

なし。

バグ

たぶん、問題ない。が、資源の解放の成否をチェックしていないので、 解放失敗等を検出することはできない。

ghttp_uri_validate()

書式

int ghttp_uri_validate( char *a_uri)

説明

ghttp_uri_validate() は、 a_uri を評価し、URI として解釈可能か検査する。

戻り値

正常の場合は 0。異常がある場合は -1 を返す。

バグ

たぶん、問題ない。が、異常の理由は教えてくれない。また、0 が返っ たからと言って、 RFC2396 にてらしてまったく問題がないとも言えない気がする。

ghttp_set_uri()

書式

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 の 構文チェックをするので、同じ問題を持っている。また、内部で使用す るメモリの確保チェックを行っていない部分があるので、メモリ確保に 失敗した場合、セグメンテーション違反を発生する可能性がある。

ghttp_set_proxy()

書式

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回しか呼び出さないことを推奨する。

ghttp_set_type()

書式

int ghttp_set_type( ghttp_request *a_request, ghttp_type a_type)

説明

ghttp_set_type() は、 a_request が使用するメソッドを a_type に 設定する。

戻り値

正常の場合は 0。未定義のメソッドの場合は -1 を返す。

バグ

たぶん、ない。

ghttp_set_body()

書式

int ghttp_set_body( ghttp_request *a_request, char *a_body, int a_len)

説明

ghttp_set_body() は、 リクエストボディとして、長さ a_lena_bodya_request に設定する。 a_body をそのままリクエストボディとして使うので、 a_body の指すメモリはリクエスト終了まで保持すること。 また、そのメモリ領域は、プログラマの責任で確保・解放すること。

戻り値

正常の場合は 0。メソッドが POST, PUT, PROPPATCH, PROPFIND, LOCK 以外の場合は -1 を返す。

バグ

たぶん、ない。

ghttp_set_sync()

書式

int ghttp_set_sync( ghttp_request *a_request, ghttp_sync_mode a_mode)

説明

ghttp_set_sync() は、 リクエストの実行時に、同期モード、非同期モードのどちらを使うか設 定する。

戻り値

正常の場合は 0。a_mode が、ghttp_sync または ghttp_async 以外の場合は -1 を返す。

バグ

たぶん、ない。

ghttp_prepare()

書式

int ghttp_prepare( ghttp_request *a_request)

説明

ghttp_prepare() は、 リクエストの実行の準備として、必要なパラメータが設定されているこ とと、設定されたパラメータに対応したリクエストヘッダの生成等を行 う。なお、proxy を経由しない場合は、http 以外の URI scheme は許 可しない。

戻り値

正常の場合は 0。異常の場合は -1 を返す。

バグ

たぶん、ない。ただし、異常の理由を知る手段はない。

ghttp_set_chunksize()

書式

void ghttp_set_chunksize( ghttp_request *a_request, int a_size)

説明

ghttp_set_chunksize() は、リクエス ト実行用のI/O バッファのサイズを設定する。回線速度が異なる場合に、 バッファサイズを変更して最適化することもできなくはない。

なお、a_size が 0 以下の場合は、バッファサイズは変更 されない。

戻り値

なし。

バグ

たぶん、ない。

ghttp_set_header()

書式

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_process()

書式

ghttp_status ghttp_process( ghttp_request *a_request)

説明

ghttp_process() は、 リクエストを発行し、サーバからの応答を取得する。非同期モードの場 合の動作は未解明。

戻り値

正常で転送が終了したとき ghttp_done、非同期モードで転送が終了し ていないとき ghttp_not_done、異常のとき ghttp_error。

バグ

ないことを期待。

ghttp_get_status()

書式

ghttp_current_status ghttp_get_status( ghttp_request *a_request)

説明

ghttp_get_status() は、 リクエストの現在の状態を取得し、 ghttp_current_status 型の構造体とし て返す。

戻り値

ghttp_current_status 型の構造体に格 納される。

バグ

a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。

ghttp_flush_response_buffer()

書式

void ghttp_flush_response_buffer( ghttp_request *a_request)

説明

ghttp_flush_response_buffer() は、 a_request の I/O バッファから取得したデータをレスポン スボディへ押し出す。これにより、非同期モードの場合、データ取得の 途中でもデータを取り出すことができるようになる。

戻り値

なし。

バグ

a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。

ghttp_get_header()

書式

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 のときの挙動は不明。

ghttp_get_header_names()

書式

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 のときの挙動は不明。

ghttp_close()

書式

int ghttp_close( ghttp_request *a_request)

説明

ghttp_close() は、 実行中のリクエストを中断する。

戻り値

正常の場合 0、異常の場合 -1 を返す。

バグ

socket の close の成否はチェックしないので、本当に close できた かどうかを確認する方法はない。

ghttp_clean()

書式

void ghttp_clean( ghttp_request *a_request)

説明

ghttp_clean() は、 レスポンスの格納領域を再初期化する。

戻り値

なし。

バグ

a_request に対する検査を行わないので、不正な a_request のときの挙動は不明。

ghttp_get_socket()

書式

int ghttp_get_socket( ghttp_request *a_request)

説明

ghttp_get_socket() は、 a_request に結びつけられた socket を取得する。

戻り値

取得した socket。存在しない場合は -1 を返す。

バグ

たぶん、ない。

ghttp_get_body()

書式

char * ghttp_get_body( ghttp_request *a_request)

説明

ghttp_get_body() は、 エンティティボディを取得する。

戻り値

取得したエンティティボディ。異常の場合は NULL を返す。

バグ

たぶん、ない。

ghttp_get_body_len()

書式

int ghttp_get_body_len( ghttp_request *a_request)

説明

ghttp_get_body_len() は、 エンティティボディの長さを取得する。

戻り値

取得したエンティティボディの長さ。異常の場合は 0 を返す。

バグ

たぶん、ない。

ghttp_get_error()

書式

char * ghttp_get_error( ghttp_request *a_request)

説明

ghttp_get_error() は、 通信中に設定されたエラーメッセージを取得する。

戻り値

設定されたエラーメッセージ。異常の場合やメッセージが設定されてい ない場合は NULL を返す。

バグ

たぶん、ない。

ghttp_parse_date()

書式

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 以外だと使えない かもしれない。

ghttp_status_code()

書式

int ghttp_status_code( ghttp_request *a_request)

説明

ghttp_status_code() は、 リクエストの実行結果のステータスコードを取得する。

戻り値

取得したステータスコード。異常の場合は、0 を返す。

バグ

たぶん、ない。

ghttp_reason_phrase()

書式

const char * ghttp_reason_phrase( ghttp_request *a_request)

説明

ghttp_reason_phrase() は、 リクエストの実行結果の Reason-Phrase (ステータスコードに対応し た文字列で、例えば、200 に対して "OK", 404 に対して "Not Found" など)を取得する。

戻り値

取得した Reason-Phrase。異常の場合は、NULL を返す。

バグ

たぶん、ない。

ghttp_set_authinfo()

書式

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 を返す。

バグ

メモリ確保周りのチェックが不十分なため、メモリ確保に失敗した場合、 セグメンテーション違反を起こす可能性が高い。

ghttp_set_proxy_authinfo()

書式

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 を返す。

バグ

メモリ確保周りのチェックが不十分なため、メモリ確保に失敗した場合、 セグメンテーション違反を起こす可能性が高い。


Copyright © 2003 杉浦 伊織
このページに関するお問い合わせは秘 書を通してください。
最終更新: Mon Feb 10 23:19:46 2003