/*---------------------------------------------------------------------------* Project: Horizon File: http_Connection.h Copyright (C)2009 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 26779 $ *---------------------------------------------------------------------------*/ #ifndef NN_HTTP_HTTP_CONNECTION_H_ #define NN_HTTP_HTTP_CONNECTION_H_ #include #include #include #include #include #include #include #include #include #ifdef __cplusplus namespace nn { namespace http { /*! @brief HTTPの通信を表すクラスです。本クラスの１つのインスタンスは、「１つのURLに対する１つのHTTP通信」を担います。 @attention @ref Initialize 以外のI/Fは、@ref Initialize 成功前に実行した場合は、 「通信先未割り当て」を表すエラー(Description==ER_CONNECTION_NOT_INITIALIZEDのResult)を返します。 */ class Connection : private nn::util::NonCopyable { public: //---------------------------------------- //! @name 初期化/終了 //@{ /*! @brief コンストラクタです。 初期化を行わないコンストラクタです。 別途 @ref Initialize を呼び出す必要があります。 */ explicit Connection(void); /*! @brief コンストラクタです。 初期化を行うコンストラクタです。 内部で@ref Initialize を呼び出します。 (別途 @ref Initialize を呼び出す必要はありません。) 引数は@ref Initialize と同様です。引数定義は、@ref Initializeを参照してください。 */ explicit Connection(const char* pUrl, RequestMethod method = REQUEST_METHOD_GET, bool isUseDefaultProxy = true); /*! @brief デストラクタです。 */ virtual ~Connection(void); /*! @brief Connection を初期化し、URL やメソッドを割り当てます。 @param[in] pUrl 通信先ホストのURLの文字列 @param[in] method HTTPリクエストのメソッド(未指定の場合、デフォルト値の @ref nn::http::REQUEST_METHOD_GET が選択されます。) @param[in] isUseDefaultProxy 機器に設定されているデフォルトのプロキシ設定を利用するか否か("利用する"はtrueです。 未指定の場合、デフォルト値のtrueが選択されます。) @return 処理の結果が返ります。
@retval Description== @ref ER_CONN_ADD 「すでに機器が管理可能な最大数のHTTP通信が存在し、通信割り当てができません」を表すエラー。 @retval Description== @ref ER_REQ_URL 「指定されたURLは不正なものです。」を表すエラー @retval Description== @ref ER_ALREADY_ASSIGN_HOST 「すでに通信先ホストが割り当て済みです。」を表すエラー @retval Description== @ref ER_CONN_PROCESS_MAX 「1プロセスの使用できるコネクションの最大数を越えています。」を表すエラー @attention 機器が同時に管理できるHTTP通信の数は有限です。@ref Initialize 時にすでに管理可能な最大数のHTTP通信が存在した場合は、エラーが返ります。 @note 本関数では通信先の割り当てのみが実施され、ネットワークレベルの接続は行われません。 ネットワーク通信が開始されるのは、@ref Connect / @ref ConnectAsync 呼び出し時となります。 */ nn::Result Initialize(const char* pUrl, RequestMethod method = REQUEST_METHOD_GET, bool isUseDefaultProxy = true); /*! @brief 通信の終了処理を実施します。
@ref Initialize 後、通信先とのHTTP処理がすべて終了した後に、実行してください。
(@ref Initialize を実行していないインスタンスに対しては、実行する必要はありません。実行しても構いませんが、何も処理は行われません。)
ある @ref Connection インスタンスで本関数を実行した後は、そのインスタンス経由で通信先の情報を取得できなくなります。
@return 処理の結果が返ります。
@attention 機器が同時に管理できるHTTP通信の数は有限です。使わなくなった通信に対しては必ずこの関数を実行して、他通信に管理リソースを回してください。 */ nn::Result Finalize(void); //@} //---------------------------------------- //! @name 通信設定 //@{ /*! @brief 接続に利用するプロキシサーバを設定します。 @param[in] pProxyName プロキシサーバのホストサーバ名 @param[in] port プロキシサーバのポート番号 @param[in] pUserName プロキシサーバのBasic認証用ユーザー名 @param[in] pPassword プロキシサーバのBasic認証用パスワード @return 処理の結果が返ります。
*/ nn::Result SetProxy(const char* pProxyName, u16 port, const char* pUserName, const char* pPassword); /*! @brief Basic認証に用いる情報を設定します。 @param[in] pUserName Basic認証用ユーザー名 @param[in] pPassword Basic認証用パスワード @return 処理の結果が返ります。
*/ nn::Result SetBasicAuthorization(const char* pUserName, const char* pPassword); /*! @brief 通信で用いるSocketのTCP受信バッファサイズを設定する。 受信バッファに使用するメモリは HTTP 内にあらかじめ確保されているメモリから割り当てられることに注意してください。 他のモジュールで作成した HTTP セッションにおいて大きな受信バッファサイズを指定していると、 設定に失敗することがあります。 従って、エラーが発生した場合には、エラーを無視しそのまま処理を続行してください。 @param[in] size 設定するTCP受信バッファサイズ @return 処理の結果が返ります。
*/ nn::Result SetSocketBufferSize(size_t size); //@} //---------------------------------------- //! @name 通信制御 //@{ /*! @brief 通信先との接続を開始します。 (同期版です。つまり「すでに機器が最大数のHTTP通信を行っている場合は、他のHTTP通信が終わるまでブロックします」。) @return 処理の結果が返ります。
@retval Description== @ref ER_CONN_CANCELED 「通信はキャンセルされました。」を表すエラー */ nn::Result Connect(void); /*! @brief 通信先との接続を開始します。 (非同期版です。つまり「すでに機器が最大数のHTTP通信を行っている場合は、エラーが返ります。」) @return 処理の結果が返ります。
@retval Description== @ref ER_MSGQ_SEND_LSN 「すでに機器が最大数のHTTP通信を行っています」を表すエラー。 @retval Description== @ref ER_CONN_CANCELED 「通信はキャンセルされました。」を表すエラー */ nn::Result ConnectAsync(void); /*! @brief 接続をキャンセルします。 @return 処理の結果が返ります。
*/ nn::Result Cancel(void); /*! @brief 接続の状況を取得します。(取得される状況の種類については、@ref nn::http::Status の定義を参照してください。) @param[out] pStatusBuf 接続状況を格納するためのバッファ @return 処理の結果が返ります。
*/ nn::Result GetStatus(Status* pStatusBuf) const; /*! @brief 接続中に発生したエラーを取得します。(取得値は最後に発生したエラーとなります。取得される状況の種類については、@ref nn::http::ResultCodeの定義を参照してください。) @param[out] pResultCodeBuf エラーを格納するためのバッファ @return 処理の結果が返ります。
*/ nn::Result GetError(ResultCode* pResultCodeBuf) const; /*! @brief HTTPレスポンスのメッセージボディ受信の進捗状況を取得します。 @param[out] pReceivedLen 「メッセージボディの受信済みデータサイズ」を格納するバッファ @param[out] pContentLen 「メッセージボディの受信予定総データサイズ」を格納するバッファ (HTTPレスポンスのContent-Lengthの値です。Content-Lengthが指定されていない場合は、0が返ります。) @return 処理の結果が返ります。
*/ nn::Result GetProgress(size_t* pReceivedLen, size_t* pContentLen) const; //@} //---------------------------------------- //! @name レスポンス受信 //@{ /*! @brief HTTPレスポンスを読み取ります。 引数で指定したバッファに、メッセージボディのデータが格納されます。
メッセージボディがバッファよりも大きい場合は、バッファに入るだけデータを格納し、エラー(Description== @ref ER_RES_BODYBUF_SHORTAGE)を返します。
その後再度 @ref Read を実行することで、前回の @ref Read でバッファに格納したデータの次のデータから、読み取りを継続できます。
すべてのメッセージボディデータの受信が完了すると、SuccessのResultが返ります。

ユーザーが指定したバッファに格納されるメッセージボディに対して、以下のデータはライブラリ側が保持しています。
これらデータの取得には、それぞれ専用のAPIを使用してください。
・レスポンスステータス - @ref GetStatusCode
・メッセージヘッダ - @ref GetHeaderField / @ref GetHeaderAll

※@ref Read の実施前にこれらAPIを利用した場合、ヘッダ部受信完了までこれら関数はブロックします。
※@ref Read の成功完了後は、ヘッダ部受信はすでに完了しているため、これら関数は結果をすぐに返します。
※@ref Read の返値のエラーは、HTTPレスポンスの受信自体に失敗したことを示します。
そのため、受信には成功し、メッセージにて通信エラー(認証失敗など)が通知された場合では、@ref Read の戻り値は成功となります。
このようなエラーを確認したい場合は、@ref GetStatusCode で取得されるステータスコードを使用してください。
※タイムアウト付きの@ref Read と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了(「HTTPレスポンスの受信が完了する」か「バッファが一杯になる」)して関数から戻るまで、長時間かかることが予想されます。
@param[out] pBodyBuf HTTPレスポンスのメッセージボディを格納するバッファ @param[in] bufLen pBodyBufのサイズ @return 処理の結果が返ります。
@retval Description== @ref ER_RES_BODYBUF_SHORTAGE 「メッセージボディがバッファよりも大きく、すべて読み取れていません。」を表すエラー @retval Description== @ref ER_SOC_DNS 「URLで指定されたホスト名に対する名前解決が失敗しました。」を表すエラー @retval Description== @ref ER_CONN_CANCELED 「通信はキャンセルされました。」を表すエラー */ nn::Result Read(u8* pBodyBuf, size_t bufLen); /*! @brief タイムアウト付きの@ref Read です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref Read と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内に「HTTPレスポンスの受信が完了する」、「バッファが一杯になる」のいずれの状態にもならなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[out] pBodyBuf HTTPレスポンスのメッセージボディを格納するバッファ @param[in] bufLen pBodyBufのサイズ @param[in] timeout タイムアウト時間 @return 処理の結果が返ります。
*/ nn::Result Read(u8* pBodyBuf, size_t bufLen, const nn::fnd::TimeSpan& timeout); /*! @brief 受信したHTTPレスポンスのメッセージヘッダから、指定したラベルに一致するフィールドの値を取得します。 ヘッダ部受信処理終了まで、本APIはブロックします。受信処理が完了するのは、以下の条件が満たされた場合です。
・全ヘッダデータの受信が完了した
・キャンセルが実行された
・通信エラーが発生した(DNS名前解決失敗時など)
他APIでヘッダ部受信処理終了がすでに完了している場合は、本APIはすぐに応答を返します。

※pFieldBufのサイズがフィールド値のサイズよりも小さい場合は、pFieldBufに格納できるだけデータを格納し、pFieldLengthCourierにはフィールド値のサイズを格納します。
※pFieldBuf==NULLまたはbufSize==0の場合、pFieldLengthCourier!=NULLであれば、フィールドの長さがpFieldLengthCourierに格納されます。
※タイムアウト付きの@ref GetHeaderField と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[in] pLabel ラベル名 @param[out] pFieldBuf フィールド値を格納するバッファ @param[in] bufSize pFieldBufのデータサイズ @param[out] pFieldLengthCourier フィールド値のデータサイズを格納するバッファ(フィールド値のデータサイズを必要としない場合は、省略可) @return 処理の結果が返ります。
@retval Description== @ref ER_SOC_DNS 「URLで指定されたホスト名に対する名前解決が失敗しました。」を表すエラー @retval Description== @ref ER_CONN_CANCELED 「通信はキャンセルされました。」を表すエラー */ nn::Result GetHeaderField(const char* pLabel, char* pFieldBuf, size_t bufSize, size_t* pFieldLengthCourier = NULL) const; /*! @brief タイムアウト付きの@ref GetHeaderField です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref GetHeaderField と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にHTTPレスポンスヘッダの受信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[in] pLabel ラベル名 @param[out] pFieldBuf フィールド値を格納するバッファ @param[in] bufSize pFieldBufのデータサイズ @param[in] timeout タイムアウト時間 @param[out] pFieldLengthCourier フィールド値のデータサイズを格納するバッファ(フィールド値のデータサイズを必要としない場合は、省略可) @return 処理の結果が返ります。
*/ nn::Result GetHeaderField(const char* pLabel, char* pFieldBuf, size_t bufSize, const nn::fnd::TimeSpan& timeout, size_t* pFieldLengthCourier = NULL) const; /*! @brief 受信したHTTPレスポンスのメッセージヘッダを取得します。 ヘッダ部受信処理終了まで、本APIはブロックします。この仕様に関する詳細は @ref GetHeaderField の説明を参照してください。
※pHeaderBufのサイズがヘッダのサイズよりも小さい場合は、pHeaderBufに格納できるだけデータを格納し、pLengthCourierにはヘッダのサイズを格納します。
※pHeaderBuf==NULLまたはbufSize==0の場合、pLengthCourier!=NULLであれば、フィールドの長さがpLengthCourierに格納されます。
※タイムアウト付きの@ref GetHeaderAll と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[out] pHeaderBuf メッセージヘッダを格納するバッファ @param[in] bufSize pHeaderBufのデータサイズ @param[out] pLengthCourier メッセージヘッダサイズを格納するバッファ(メッセージヘッダサイズを必要としない場合は、省略可) @return 処理の結果が返ります。(結果定義は、@ref GetHeaderField と同様)
*/ nn::Result GetHeaderAll(char* pHeaderBuf, size_t bufSize, size_t* pLengthCourier = NULL) const; /*! @brief タイムアウト付きの@ref GetHeaderAll です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref GetHeaderAll と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にHTTPレスポンスヘッダの受信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[out] pHeaderBuf メッセージヘッダを格納するバッファ @param[in] bufSize pHeaderBufのデータサイズ @param[in] timeout タイムアウト時間 @param[out] pLengthCourier メッセージヘッダサイズを格納するバッファ(メッセージヘッダサイズを必要としない場合は、省略可) @return 処理の結果が返ります。(結果定義は、@ref GetHeaderField と同様)
*/ nn::Result GetHeaderAll(char* pHeaderBuf, size_t bufSize, const nn::fnd::TimeSpan& timeout, size_t* pLengthCourier = NULL) const; /*! @brief 受信したHTTPレスポンスのステータスコードを取得します。 ヘッダ部受信処理終了まで、本APIはブロックします。この仕様に関する詳細は @ref GetHeaderField の説明を参照してください。
※タイムアウト付きの@ref GetStatusCode と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[out] pStatusCodeCourier ステータスコードを格納するバッファ @return 処理の結果が返ります。(結果定義は @ref GetHeaderField と同様)
*/ nn::Result GetStatusCode(s32* pStatusCodeCourier) const; /*! @brief タイムアウト付きの@ref GetStatusCode です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref GetStatusCode と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にHTTPレスポンスヘッダの受信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[out] pStatusCodeCourier ステータスコードを格納するバッファ @param[in] timeout タイムアウト時間 @return 処理の結果が返ります。(結果定義は、@ref GetHeaderField と同様)
*/ nn::Result GetStatusCode(s32* pStatusCodeCourier, const nn::fnd::TimeSpan& timeout) const; //@} //---------------------------------------- //! @name 送信データ設定(HTTPリクエストヘッダ、POST) //@{ /*! @brief HTTPリクエストで送信するメッセージヘッダのフィールドを追加します。 @param[in] pLabel フィールドのラベル名 @param[in] pValue フィールドの内容 @return 処理の結果が返ります。
*/ nn::Result AddHeaderField(const char* pLabel, const char* pValue); /*! @brief POSTデータの @ref Connect 前設定用API(ASCII文字列用)です。 HTTPリクエストで送信するPOSTデータ(ASCII文字列)を追加します。
このAPIは @ref Connect 実行前の設定に使用します。設定後の @ref Connect 実行によって、POSTデータが送信されます。
同じラベルのデータが先に追加されていた場合は、データを更新します。（つまり前に追加したデータを削除してから、追加します。）

すべてのPOSTデータが @ref AddPostDataAscii のみで設定された場合、送信データはラベル、データ共にエンコードされた上で送信されます。
(HTTPヘッダのContent-Typeには"x-www-form-urlencoded"が設定されます。)

一つでも @ref AddPostDataBinary で設定したデータがある場合は、POSTデータはすべて、エンコードされずに(そのまま)送信されます。
(HTTPヘッダのContent-Typeには"multipart/form-data"が設定されます。)
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @return 処理の結果が返ります。
*/ nn::Result AddPostDataAscii(const char* pLabel, const char* pValue); /*! @brief POSTデータの @ref Connect 前設定用API(バイナリデータ用)です。 HTTPリクエストで送信するPOSTデータ(バイナリデータ)を追加します。
このAPIは @ref Connect 実行前の設定に使用します。
設定後の @ref Connect実行によって、POSTデータが送信されます。
同じラベルのデータが先に追加されていた場合は、データを更新します。
（つまり前に追加したデータを削除してから、追加します。）

@ref AddPostDataBinary で設定したデータがある場合は、POSTデータはすべて、エンコードされずに(そのまま)送信されます。
(HTTPヘッダのContent-Typeには"multipart/form-data"が設定されます。)
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @return 処理の結果が返ります。
*/ nn::Result AddPostDataBinary(const char* pLabel, const void* pValue, size_t valueSize); /*! @brief POSTデータの @ref Connect 前設定用API(Rawデータ用)です。 HTTPリクエストで送信するPOSTデータすべてを、一括で設定します。
バイナリ形式ですが、POSTデータ全体を直接Rawデータで設定します。
(他のAPIは、POSTデータのラベル部とバリュー部を設定します。)

このAPIは @ref Connect 実行前の設定に使用します。
設定後の @ref Connect 実行によって、POSTデータが送信されます。

POSTデータ全体を設定しますので、本APIによる設定以降にPOSTデータ部分設定API(@ref AddPostDataAscii と @ref AddPostDataBinary)
を呼び出すと、エラー(Descriptionは @ref nn::http::ER_POST_ADDED_ANOTHER)が返ります。
本APIによる設定以降に、再び本APIでRawデータを設定した場合は、前回設定したデータは破棄され、設定データが更新されます。
@param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @return 処理の結果が返ります。
*/ nn::Result AddPostDataRaw(const void* pValue, size_t valueSize); /*! @brief POSTデータ遅延設定モード(@ref Connect 後のデータ指定モード)に設定します。 この関数を実行すると、POSTデータの遅延設定(@ref Connect / @ref ConnectAsync 実行後に、SendPostData××()によってデータを設定)が可能となります。

POSTデータ遅延設定モードでは、@ref Connect / @ref ConnectAsync 実行後、SendPostData××()は何回実行しても構いません。
POSTデータは、SendPostData××()の同期処理としてそのまま送信されます。よって送信が完了するまで、SendPostData××()はブロックします。
すべてのPOSTデータの設定が完了したら、@ref NotifyFinishSendPostData を実行しなければなりません。

NotifyFinishSendPostData()の実行後、HTTPレスポンスの受信に移行します。
@param[in] dataType POSTデータのタイプです。 @ref nn::http::POST_DATA_TYPE_URLENCODE : 設定したデータは、ASCIIデータの場合(つまり@ref SendPostDataAscii を使った場合)には、データがURLエンコードされて送信されます。
使用できるSendPostData××()は、@ref SendPostDataAscii と @ref SendPostDataBinary です。
@ref SendPostDataAscii　を使った場合は、URLエンコードされた[<ラベル名>=<データ内容>]のデータが送信されます。
@ref SendPostDataBinary　を使った場合は、URLエンコードされない[<ラベル名>=<データ内容>]のデータが送信されます。
１回のSendPostData××()で設定されたラベルとデータは、Chunkedデータの一単位としてまとめて送信されます。


@ref nn::http::POST_DATA_TYPE_MULTIPART : 設定したデータは、MIMEのマルチパートデータとして送信されます。
使用できるSendPostData××()は、@ref SendPostDataAscii と @ref SendPostDataBinaryです。
１回のSendPostData××()で設定されたラベルとデータは、boundaryデータやヘッダフィールドが先頭に付与されて、Chunkedデータの一単位としてまとめて送信されます。
設定したラベルデータは、Content-Dispositionフィールドのnameとして設定されます。
(すなわち"Content-Disposition: form-data; name=[ラベル]"というヘッダフィールドが、Chunkedデータのboundaryデータの後に付与されます。)
@ref SendPostDataBinaryでラベルとデータを設定した場合は、Chunkedデータのboundaryデータの後に、Content-Typeフィールドが付与されます。
(フィールド内容は"Content-Type: application/octet-stream\\r\\nContent-Transfer-Encoding: binary\\r\\n"となります。
@ref SendPostDataAscii で設定したデータのChunkedデータには、このフィールドは付与されません。)


@ref nn::http::POST_DATA_TYPE_RAW : 設定したデータは、そのまま送信されます。使用できるSendPostData××()は、@ref SendPostDataRaw のみです。
１回の @ref SendPostDataRaw で設定されたデータは、Chunkedデータの一単位としてまとめて送信されます。 @return 処理の結果が返ります。
*/ nn::Result SetLazyPostDataSetting( PostDataType dataType ); /*! @brief POSTデータ遅延設定モード時、全POSTデータ設定完了を通知します。 詳しくは @ref SetLazyPostDataSetting の説明を参照してください。 @return 処理の結果が返ります。
*/ nn::Result NotifyFinishSendPostData( void ); /*! @brief HTTPリクエストのPOSTデータのエンコードタイプを設定します。 @param[in] type 設定するエンコードタイプ @return 処理の結果が返ります。
*/ nn::Result SetPostDataEncoding(EncodingType type); /*! @brief POSTデータ遅延設定モード時のPOSTデータ設定用API(ASCII文字列用)です。 POSTデータ遅延設定モード(@ref SetLazyPostDataSetting でモードに入ることができる。)において、@ref Connect / @ref ConnectAsync 実行後に使用することができます。 POSTデータ遅延設定モードの詳細は、@ref SetLazyPostDataSetting の説明を参照してください。 ※タイムアウト付きの@ref SendPostDataAscii と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @return 処理の結果が返ります。
*/ nn::Result SendPostDataAscii(const char* pLabel, const char* pValue); /*! @brief タイムアウト付きの@ref SendPostDataAscii です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref SendPostDataAscii と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にPOSTデータの送信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @param[in] timeout タイムアウト時間 @return 処理の結果が返ります。
*/ nn::Result SendPostDataAscii(const char* pLabel, const char* pValue, const nn::fnd::TimeSpan& timeout); /*! @brief POSTデータ遅延設定モード時のPOSTデータ設定用API(バイナリデータ用)です。 POSTデータ遅延設定モード(@ref SetLazyPostDataSetting でモードに入ることができる。)において、@ref Connect / @ref ConnectAsync 実行後に使用することができます。 POSTデータ遅延設定モードの詳細は、@ref SetLazyPostDataSetting の説明を参照してください。 ※タイムアウト付きの@ref SendPostDataBinary と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @return 処理の結果が返ります。
*/ nn::Result SendPostDataBinary(const char* pLabel, const void* pValue, size_t valueSize); /*! @brief タイムアウト付きの@ref SendPostDataBinary です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref SendPostDataBinary と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にPOSTデータの送信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[in] pLabel データのラベル名 @param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @param[in] timeout タイムアウト時間 @return 処理の結果が返ります。
*/ nn::Result SendPostDataBinary(const char* pLabel, const void* pValue, size_t valueSize, const nn::fnd::TimeSpan& timeout); /*! @brief POSTデータ遅延設定モード時のPOSTデータ設定用API(RAWデータ用)です。 POSTデータ遅延設定モード(@ref SetLazyPostDataSetting でモードに入ることができる。)において、@ref Connect / @ref ConnectAsync 実行後に使用することができます。 POSTデータ遅延設定モードの詳細は、@ref SetLazyPostDataSetting の説明を参照してください。 ※タイムアウト付きの@ref SendPostDataRaw と異なり、この関数はタイムアウトしません。つまり処理が終了するまでは、関数から戻りません。
そのため、例えば通信速度の低い環境で使用した場合には、処理が終了して関数から戻るまで、長時間かかることが予想されます。
@param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @return 処理の結果が返ります。
*/ nn::Result SendPostDataRaw(const void* pValue, size_t valueSize); /*! @brief タイムアウト付きの@ref SendPostDataRaw です。 タイムアウトが指定できること以外は、タイムアウト指定無しの@ref SendPostDataRaw と同機能のAPIです。機能の詳細はタイムアウト無しAPIのリファレンスを参照してください。
タイムアウト時間以内にPOSTデータの送信が完了しなかった場合、@ref ResultTimeout が返ります。
@ref ResultTimeout()が返った場合、そのコネクションは自動的にキャンセルされた状態になっています。(つまり@ref Cancel が内部的に実施されています。)
@param[in] pValue データの内容 @param[in] valueSize pValueのデータサイズ @param[in] timeout タイムアウト時間 @return 処理の結果が返ります。
*/ nn::Result SendPostDataRaw(const void* pValue, size_t valueSize, const nn::fnd::TimeSpan& timeout); //@} //---------------------------------------- //! @name HTTPS用設定 //@{ /*! @brief CA証明書を設定します。複数回実行することで、複数個の証明書を設定することもできます。 @param[in] pCertData 証明書データ。データフォーマットは、X.509 v3の証明書データ(ASN.1定義)をDERエンコードしたバイナリデータ。 @param[in] certDataSize pCertDataのサイズ 。 @return 処理の結果が返ります。
*/ nn::Result SetRootCa(const u8* pCertData, size_t certDataSize); /*! @brief 機器内蔵CA証明書を設定します。複数回実行することで、複数個の証明書を設定することもできます。 @param[in] inCaCertName 対象の機器内蔵CA証明書(ssl の @ref nn::ssl::InternalCaCertの値。) @return 処理の結果が返ります。
*/ nn::Result SetRootCa( InternalCaCertId inCaCertName ); /*! @brief CA証明書ストアを設定します。(複数のHTTPS通信で同じCA証明書セットを使いまわしたい場合に利用します。) 設定した証明書ストアは、設定先のHTTPS通信実施中は解放しないでください。 @param[in] certStore 設定する証明書ストア @return 処理の結果が返ります。
*/ nn::Result SetRootCaStore(CertStore& certStore); /*! @brief 証明書と秘密鍵のデータからクライアント証明書を設定します。 @param[in] pCertData 証明書データ。データフォーマットは、X.509 v3の証明書データ(ASN.1定義)をDERエンコードしたバイナリデータ。 @param[in] certDataSize pCertDataのサイズ 。 @param[in] pPrivateKeyData 秘密鍵のデータ。データフォーマットは、X.509の鍵データ(ASN.1定義)をDERエンコードしたバイナリデータ。 @param[in] privateKeyDataSize pPrivateKeyDataのサイズ 。 @return 処理の結果が返ります。
*/ nn::Result SetClientCert(const u8* pCertData, size_t certDataSize, const u8* pPrivateKeyData, size_t privateKeyDataSize); /*! @brief 機器内蔵クライアント証明書を設定します。 @param[in] inClientCertName 対象の機器内蔵クライアント証明書(sslの @ref nn::ssl::InternalClientCertの値。) @return 処理の結果が返ります。
*/ nn::Result SetClientCert( InternalClientCertId inClientCertName ); /*! @brief ClientCertインスタンスを用いてクライアント証明書を設定します。(複数のHTTPS通信で同じクライアント証明書を使いまわしたい場合に利用します。) 設定したクライアント証明書は、設定先のHTTPS通信実施中は解放しないでください。 @param[in] clientCert 設定するクライアント証明書。 @return 処理の結果が返ります。
*/ nn::Result SetClientCert(ClientCert& clientCert); /*! @brief SSL通信中に発生したエラーを取得します。 (エラーコードは @ref nn::ssl::ResultCode の値となります。取得される値は、本関数を呼び出す前の最後に発生したエラーコードとなります。) @param[out] pResultCodeBuf エラーを格納するためのバッファ @return 処理の結果が返ります。
*/ nn::Result GetSslError(s32* pResultCodeBuf) const; /*! @brief SSLのサーバ検証に関するオプションを設定します。
※ @ref nn::ssl::VerifyOption 列挙体に定義が存在する以下の検証は、デフォルトで実施されます。
CommonName検証(@ref nn::ssl::VERIFY_COMMON_NAME)
RootCA検証(@ref nn::ssl::VERIFY_ROOT_CA)
SubjectAlternativeName検証(@ref nn::ssl::VERIFY_SUBJECT_ALT_NAME)
@param[in] verifyOption SSLのサーバ検証に関するオプション設定。デフォルトのサーバ検証では実施しない設定となっている検証オプションを、実施する場合に利用します。 (デフォルトのサーバ検証を用いる場合は、この引数は省略できます。) 引数には、実施する検証オプションを表す @ref nn::ssl::VerifyOption 列挙体の値を設定します。 （複数の値を設定したい場合は、複数値の論理和を設定します。）
現在この引数に設定可能な値は、以下となります。
@ref nn::ssl::VERIFY_DATE : 証明書の期限切れ検証を実施します。
@ref nn::ssl::USE_SESSION_CACHE : resumptionを利用します。(つまり同じホストに連続で接続する際、セッションの再利用を試みます。)
@ref nn::ssl::VERIFY_EV : EV証明書検証を実施します(この検証では、サーバ証明書がEV証明書に紐づいたもので無い限り、検証失敗となります。)
※本APIによるオプション設定は、設定対象の通信開始前（つまり @ref Connect / @ref ConnectAsync の呼び出し前）に実施する必要があります。 @return 処理の結果が返ります。
*/ nn::Result SetVerifyOption(u32 verifyOption); /** @brief 指定したビットのSSL通信の検証内容を削除します。 デフォルトで検証する項目は安全を守るためのものです。
デバッグ目的以外で検証項目を減らさないでください。
※本APIによるオプション設定は、設定対象の通信開始前（つまり @ref Connect / @ref ConnectAsync の呼び出し前）に実施する必要があります。 @param[in] excludeVerifyOptions SSLの検証方法に関して、除外対象を表すオプション。 除外したい検証方法を表す @ref nn::ssl::VerifyOption 列挙体の値を設定します。（複数の値を設定したい場合は、複数値の論理を設定します。） 現在この引数に設定可能な値は、以下となります。
@ref nn::ssl::VERIFY_COMMON_NAME : 証明書の CommonName が 対象ホストの名称と一致するか検証します。
@ref nn::ssl::VERIFY_SUBJECT_ALT_NAME : CommonNameの検証を行う際に、証明書にSubjectAltNameの記述がある場合はそちらを優先して使用します。
@ref nn::ssl::VERIFY_ROOT_CA : 証明書の Root CA を検証します。
@return 処理の結果が返ります。
*/ nn::Result DisableVerifyOptionForDebug( u32 excludeVerifyOptions ); /*! @brief [deprecated]廃止予定のAPIです。 機器内のデフォルト証明書をCA証明書として利用するように設定します。 @return 処理の結果が返ります。
*/ nn::Result SetRootCaDefault( void ); /*! @brief [deprecated]廃止予定のAPIです。 機器内のデフォルトクライアント証明書をクライアント証明書として利用するように設定します。 @return 処理の結果が返ります。
*/ nn::Result SetClientCertDefault( void ); //@} private: /** @brief HTTPのコネクションハンドル。 */ ConnectionHandle m_ConnectHandle; /** @brief HTTPプロセスとのコネクション専用IPCセッション */ nn::Handle m_privateIpcSession; /** @brief HTTPプロセスとのコネクション専用IPCクライアント */ mutable ConnectionIpc m_PrivateIpcClient; /*! @brief 接続に利用するプロキシサーバを、デフォルトサーバに設定します。 @return 処理の結果が返ります。
*/ nn::Result SetProxyDefault(void); /** * @brief コネクションが設定済みか否かを返す。「コネクションが設定済み」とは、Create関数でコネクト先と手段が指定されているか否かである。 * @return コネクションが設定済みか否か(trueが設定済み) */ bool IsConnected() const { return (m_ConnectHandle > 0) ? true : false; } /** * @brief コネクション専用IPCクライアントを割り当てます。 * @return 処理の結果。 */ Result AssignPrivateIpcClient(); }; } // end of namespace http } // end of namespace nn #endif // __cplusplus #include /*! @addtogroup nn_http http @{ @defgroup nn_http_Connection_c Connection (C) @brief @ref nn::http::Connection の C インタフェースモジュールです。 @{ */ /*! @struct nnhttpConnection @brief HTTPのConnectionを表す C の構造体です。 @brief 対応するクラス @ref nn::http::Connection を参照してください。 */ NN_UTIL_DETAIL_CLIBIMPL_DEFINE_BUFFER_CLASS(nnhttpConnection, nn::http::Connection, 16, u32); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::Initialize を参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionInitialize(nnhttpConnection* this_, const char *pUrl, nnHttpRequestMethod method); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::Finalize を参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionFinalize(nnhttpConnection* this_); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::Connect を参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionConnect(nnhttpConnection* this_); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::ConnectAsync を参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionConnectAsync(nnhttpConnection* this_); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::Cancelを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionCancel(nnhttpConnection* this_); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::Readを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionRead(nnhttpConnection* this_, u8* pBodyBuf, u32 bufLen); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetStatusを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetStatus(const nnhttpConnection* this_, nnHttpStatus* pStatusBuf); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetProgressを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetProgress(const nnhttpConnection* this_, u32* pReceivedLen, u32* pContentLen); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetErrorを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetError(const nnhttpConnection* this_, nnHttpResultCode* pResultCodeBuf); /* 接続設定 */ /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetProxyを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetProxy(nnhttpConnection* this_, const char* pProxyName, u16 port, const char* pUserName, const char* pPassword); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetBasicAuthorizationを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetBasicAuthorization(nnhttpConnection* this_, const char *pUserName, const char *pPassword); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetSocketBufferSizeを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetSocketBufferSize(nnhttpConnection* this_, u32 size); /* HTTPリクエスト設定 */ /*! @brief 対応する C++ 関数 @ref nn::http::Connection::AddHeaderFieldを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionAddHeaderField(nnhttpConnection* this_, const char* pLabel, const char* pValue); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::AddPostDataAsciiを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionAddPostDataAscii(nnhttpConnection* this_, const char* pLabel, const char* pValue); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::AddPostDataBinaryを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionAddPostDataBinary(nnhttpConnection* this_, const char* pLabel, const char* pValue, u32 length); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::AddPostDataRawを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionAddPostDataRaw(nnhttpConnection* this_, const char* pValue, u32 length); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetLazyPostDataSettingを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetLazyPostDataSetting(nnhttpConnection* this_, nnHttpPostDataType dataType); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::NotifyFinishSendPostDataを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionNotifyFinishSendPostData(nnhttpConnection* this_); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetPostDataEncodingを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetPostDataEncoding(nnhttpConnection* this_, nnHttpEncodingType type); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SendPostDataAsciiを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSendPostDataAscii(nnhttpConnection* this_, const char* pLabel, const char* pValue); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SendPostDataBinaryを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSendPostDataBinary(nnhttpConnection* this_, const char* pLabel, const void* pValue, size_t length); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SendPostDataRawを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSendPostDataRaw(nnhttpConnection* this_, const void* pValue, u32 length); /* HTTPレスポンス取得 */ /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetHeaderFieldを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetHeaderField(const nnhttpConnection* this_, const char* pLabel, char* pFieldBuf, size_t bufSize, size_t* pFieldLengthCourier); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetHeaderAllを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetHeaderAll(const nnhttpConnection* this_, char* pHeaderBuf, size_t bufSize, size_t* pLengthCourier); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetStatusCodeを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetStatusCode(const nnhttpConnection* this_, s32* pStatusCodeCourier); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::GetSslErrorを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionGetSslError(const nnhttpConnection* this_, s32* pResultCodeBuf); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetVerifyOptionを参照してください。 */ NN_EXTERN_C nnResult nnhttpConnectionSetVerifyOption(nnhttpConnection* this_, u32 verifyOption); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetRootCaを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetRootCa(nnhttpConnection* this_, const u8 *pCertData, size_t certDataSize); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetRootCaを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetInternalRootCa( nnhttpConnection* this_, NnHttpInternalCaCertId inCaCertName ); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetRootCaStoreを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetRootCaStore( nnhttpConnection* this_, nnhttpCertStore* pCertStore); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetClientCertを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetClientCert(nnhttpConnection* this_, const u8* pCertData, size_t certDataSize, const u8* pPrivateKeyData, size_t privateKeyDataSize); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetClientCertを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetInternalClientCert(nnhttpConnection* this_, NnHttpInternalClientCertId inClientCertName ); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::SetClientCertを参照してください。 */ NN_EXTERN_C nnResult nnhttpSetClientCertObj(nnhttpConnection* this_, nnhttpClientCert* pClientCert); /*! @brief 対応する C++ 関数 @ref nn::http::Connection::DisableVerifyOptionForDebugを参照してください。 */ NN_EXTERN_C nnResult nnhttpDisableVerifyOptionForDebug(nnhttpConnection* this_, u32 verifyOption); /*! @} @} */ #endif /* NN_HTTP_HTTP_CONNECTION_H_ */