WebServer

ドキュメントの概要: UT3 における HTTP WebServer 実装の使い方と API の説明。

ドキュメントの変更ログ: ドキュメント作成。

概要

このドキュメントでは、WebServer の使い方と新しい WebApplications の作成方法を説明します。WebServer が使用するネットワーク接続に関する低レベルの情報は、TcpLinkJP を参照してください。

このドキュメントは、読者が HTTP プロトコルに関する基本的な知識を持っていることを前提としています。実際には HTTP の詳細まで把握する必要はありませんが、理解していれば役に立ちます。

WebServer は HTTP プロトコルのサブセットのみサポートしていますが、webapplications でこの機能を拡張できます。サポートされているのは GET と POSTリクエストだけです。

構造

WebServer の機能は以下のクラスで構成されています。

WebServer

これは WebServer のエントリーポイントで、接続とアプリケーションを管理します。

WebConnection

このクラスは WebServer acceptor (アクセプタ) クラスです。WebServer に接続するクライアントごとに、このクラスのインスタンスが作成されます。接続と、webapplication にリクエストを渡す前のプリプロセスを管理します。

WebRequest

このクラスは WebServer が受け取る HTTP リクエストを具現化します。

WebResponse

このクラスはリクエストへの応答を提供する機能を実装します。

WebApplication

このクラスの実装は、リクエストの処理と応答の生成を担当します。WebServer を使用する場合、このクラスを拡張します。

HTTP リクエストのプロセス

1. クライアントが WebServer に接続します。
2. WebConnection が作成され、 WebServer の接続カウンタが増分します。
3. WebConnection.Accepted が呼び出されます。
   1. 終了タイマーが開始します。接続は 30 秒間だけオープン状態になります。
4. WebConnection.ReceivedText 。 接続はリクエストを受け取ります。
   1. リクエストヘッダを処理している間に、データを複数行に分割します。
   2. リクエストヘッダを処理します。
      1. リクエスト URL にある、提供されたリクエスト変数を処理します。
      2. GET リクエストの場合:
         1. WebRequest と WebResponse インスタンスを作成します。
         2. 関連する webapplication を見つけます。
         3. webapplication が見つからない場合、デフォルト アプリケーションへの HTTP リダイレクトを用いて応答します (設定されている場合)。
      3. POST リクエスト の場合:
         1. WebRequest と WebResponse インスタンスを作成します。
         2. 関連する webapplication を見つけます。
      4. ヘッダを処理します。これは WebRequest.ProcessHeaderString が行います。
         1. Authorization: Basic の場合、認証ユーザー名とパスワードを復号化します。
         2. Content-Length の場合、 ContentType 変数を設定します。
         3. Content-Length の場合、 ContentLength 変数を設定します。
   3. リクエストのチェック:
      1. WebResponse が作成されなかった場合、HTTP 400 エラーを返します。
      2. webapplication が見つからなかった場合、HTTP 404 エラーを返します。
   4. WebRequest.ContentLength が 0 より大きく、これが POST リクエストの場合、追加データを読み取ります。
   5. † WebApplication.PreQuery を呼び出します。結果が TRUE の場合:
      1. † WebApplication.Query を呼び出します。
      2. † WebApplication.PostQuery を呼び出します。
   6. クリーンアップを初期化します。
      1. すべての変数を設定解除します。
      2. 接続を閉じます。

† これらは各ユーザーが作成する部分です。

WebApplication の作成

WebServer の機能を拡張するには、通常は webapplication を作成します。これを行うには、 WebApplication クラスのサブクラスを作成して、少なくとも WebApplication.Query メソッドを実装します。

IpDrv に、 HelloWeb という実装例を収めてあります。

作成した webapplication を登録すると、その WebServer だけが使用します。webapplication を登録するには、WebServer 構成を更新する必要があります。 ??Web.ini ファイルを編集し、 [IpDrv.WebServer] セクションを更新します。

Applications[x]=MyPackage.MyWebApplication
ApplicationPaths[x]=/myweb

ここで、 x はフリースロットで、最高 10 までの webapplication を構成できます。 webapplication には、 HTTP://ip:port/myweb 経由でアクセスします。

WebServer が開始すると、すべての webapplications を作成して初期化し、この webapplication の path 変数を ApplicationPaths 値に設定します。webapplication の初期化を実行するために init() 関数を実装します。WebServer の終了時には、 CleanupApp() 関数を呼び出します。この関数では、作成したすべてのアクタ参照を null にしてください (変数を none に設定します)。

リクエスト プロセス で説明したように、最初に呼び出される webapplication の関数は PreQuery(..) です。この関数が True を返した場合 (デフォルトの動作)、続けて Query(..) と PostQuery(..) 関数を呼び出します。3 つの関数はすべて同じ 2 つの引数 (WebRequest と WebResponse) のインスタンスを受け取ります。クラス名から分かるように、 WebRequest インスタンスにはユーザーが出した HTTP リクエストに関する情報が含まれていて、 WebResponse インスタンスはリクエストへの応答を生成するのに使うことができます。 WebRequest インスタンスの URI 変数には、作成された相対 URL が含まれます。この webapplication のパスは、元の URI から抜き出されたものです。

リクエストの処理

クライアントのリクエストは WebRequest インスタンス内に格納され、webapplication の Query に渡されます。

おそらく、 WebRequest 内の最も大切な変数は URI 変数でしょう。これには webapplication ドメイン内のリクエスト ページが含まれています。例えば、クライアントがリクエスト http://ip:port/myweb/some/page?foo=bar を出すと、 URI 変数には値 /some/page が与えられ、webapplication の /myweb 接頭辞が削除されてリクエスト変数は他の場所に格納されます。

GET または POST リクエストのリクエスト変数を取得するには、 GetVariable 、 GetVariableCount 、 GetVariableNumber と GetVariables 関数を用いる必要があります。 GetVariable 関数により、指定されたリクエスト変数の最初の値を求めることができます。前述の GetVariable("foo") の例では、 bar を返します。ときには、http://ip:port/myweb/some/page?foo=bar&quux のように同じ名前のリクエスト変数が複数ある場合があります。このような場合、 GetVariableCount("foo") を使って該当する変数の数を取得し、次に GetVariableNumber("foo, X) を使って各値を得ることができます。

リクエストヘッダも、 GetHeader と GetHeaders 関数を使って読み取ることができます。HTTP ヘッダの Content-Type 、 Content-Length 、 Authentication が処理され、特別な変数として格納されます。 Content-Type と Content-Length は POST リクエストでだけ使用されます。 Authentication リクエストヘッダは基本認証リクエストの場合のみ処理され、 WebRequest オブジェクトの username と password 変数には、複合化した値が格納されます。

以下の例には、リクエストの典型的な処理方法が示されています。

function Query(WebRequest Request, WebResponse Response)
{
    // 各 "page" は個別の関数として処理される
    switch (request.URI)
    {
        case "/page1"
            doPage1(request, response);
            break;
        case "/page2"
            doPage2(request, response);
            break;
        // etc.
    }
}

function doPage1(WebRequest Request, WebResponse Response)
{
    if (request.getVariable("action") ~= "save")
    {
        // 受け取った設定を保存
    }
    // 応答を生成
}

応答の生成

webapplication が応答を提供しないときに、WebServer が提供するデフォルトの応答はありません。クライアントの役に立つ情報を生成することはごく稀です。そのため、webapplication でコンテンツを生成する必要があります。

クライアントへの応答は、 WebResponse オブジェクトを使って生成します。応答の最も基本的な生成方法は、 SendText メソッドを用いてコンテンツを返すことですが、常に UnrealScript (Unreal スクリプト) を用いて応答を生成する代わりに、通常はこれにひと工夫加えたり、ほぼ静的なコンテンツを使いたくなるところです。

WebResponse オブジェクトを用いた応答生成の基本的な流れは以下のとおりです。

1. コンテンツを定義: AddHeader 、 Subst 、 ClearSubst 、 LoadParsedUHTM 、 headers 、 CharSet
2. HTTPResponse
3. SendStandardHeaders
4. コンテンツ送信: IncludeUHTM 、 SendText 、 IncludeBinaryFile

最初の 3 つのステップは完全にオプションです。

WebResponse は、以下に示す標準 HTTP ヘッダ生成しますが、これらはカスタムヘッダの前に送信されるものです。

Server

"UnrealEngine IpDrv Web Server Build ..."

Content-Type

SendStandardHeaders 呼び出しが提供する ContentType 引数の値。

Cache-Control

"max-age=..."、WebServer の ExpirationSeconds の値。

Expires

"..."、WebServer の ExpirationSeconds の値。

Connection

"Close"、WebServer は一度に 1 つのリクエストだけ処理します。

応答データの作成には、3 つの方法がよく使われます。

1. 手動でテキストを送信
2. ファイルをそのまま送信
3. 処理された UHTM ファイル

手動でテキストを送信

SendText 関数は、web ブラウザへの応答ドキュメントを手動で作成するのに使います。このメソッドを用いた webapplication の例については、 HelloWeb クラスを参照してください。

ファイルをそのまま送信

WebResponse オブジェクトは、 IncludeBinaryFile 関数 (ディスクに保存されている状態のままのファイルをクライアントに送信する) を提供しています。この関数は、画像など静的ファイルの送信に良く使われます (ImageServer クラスを参照)。

送信に含めるファイルは、 UDK/web ディレクトリ内に置く必要があります。

注意: IncludeBinaryFile は、応答ヘッダが送信されたかどうかの確認を行いません。そのため、 IncludeBinaryFile を呼び出す前に SendStandardHeaders を呼び出す必要があります。

処理された UHTM ファイル

UHTM は、テキストファイルを処理し、特定の変数やディレクティブを置換するのに使われるテンプレートシステムです。これらのファイルは HTML ファイルでなくてもよく、任意のテキストファイルを使用できます。

2 つの特別な構文があります。まず、置換される変数は、構文 <%var_name%> を用いて作成します。 var_name は変数の名前です。変数の値は、 Subst 関数を使って設定します。SGML コメント内部では、変数を置換できないことに注意してください。つまり、<!-- <%var_name%> --> はそのまま残ります。

2 番目の構文は <!-- #include file="file.inc" --> で、これにより、現在のファイルの指定位置にファイル file.inc を読み込みます。読み込んだファイルについても、追加の変数や include ディレクティブを読み取るために処理されます。

LoadParsedUHTM と IncludeUHTM 関数がこのファイルを処理します。 LoadParsedUHTM 関数は処理したファイルを文字列として返すのに対し、 IncludeUHTM は処理した UHTM ファイルを web ブラウザに送信します。通常、新しい置換変数の作成には LoadParsedUHTM を使います。

API

WebApplication

フィールド

Path

このフィールドは、webapplication に設定されているベースパスに設定されます。 リンクを適切に作成するのにこのフィールドを使います。

関数

Init

function Init()

webapplication インスタンスが作成された直後に呼び出します。重要な初期化を行うのに使います。このメソッドを呼び出して色々なことを実行するのは推奨されていません。この webapplication の最初のリクエストが発生するまで、完全な初期化を遅延するほうが良い場合があります。

CleanupApp

function CleanupApp()

WebServer が破壊される前に呼び出します。このメソッドにより、webapplication 内のすべてのアクタ参照を none に設定し、メモリリークを防ぐようにしてください。

PreQuery

function bool PreQuery(WebRequest Request, WebResponse Response)

この webapplication が指定クエリーを処理するかどうかを調べるために呼び出します。 False を返した場合、 Query と PostQuery メソッドは呼び出されません。

Query

function Query(WebRequest Request, WebResponse Response)

PreQuery の呼び出しが True を返した後に呼び出します。

PostQuery

function PostQuery(WebRequest Request, WebResponse Response)

Query の呼び出しが返された後に呼び出します。

WebRequest

フィールド

RemoteAddr

このリクエストを作成したクライアントのアドレス。

URI

リクエスト URL。このフィールドは、webapplication の接頭辞が処理されるときにそこから取り出します。

Username

リクエストが基本 HTTP 認証ヘッダを含む場合に、復号化して取得したユーザー名。この詳細は、RFC 2617 を参照 してください。

Password

リクエストが基本 HTTP 認証ヘッダを含む場合に、復号化して取得したパスワード。

ContentLength

POST リクエストのバイト数。

ContentType

POST データのコンテンツの MIME タイプ。

RequestType

リクエストの種類に応じて、 Request_GET または Request_POST に設定されます。

関数

DecodeBase64

native final function string DecodeBase64(string Encoded)

base64 エンコードの文字列を復号化します。

EncodeBase64

native final function string EncodeBase64(string Decoded)

文字列を base64 に符号化します。

AddHeader

native final function AddHeader(string HeaderName, coerce string Value)

リクエストヘッダをデータ構造に追加します。この関数はリクエストの処理中に使われるもので、webapplication から呼び出すことはありません。

GetHeader

native final function string GetHeader(string HeaderName, optional string DefaultValue)

指定されたリクエストヘッダの値を取得します。リクエスト内にヘッダが存在しない場合は、デフォルト値を返します。同名のリクエストヘッダが複数存在する場合は、最後に受け取ったヘッダしか返さない点に注意してください。ヘッダの名前では、大文字と小文字が区別されます。

GetHeaders

native final function GetHeaders(out array headers)

受け取ったすべてのヘッダの名前を取得します。

AddVariable

native final function AddVariable(string VariableName, coerce string Value)

受け取ったリクエスト変数を登録します。この関数はリクエストの処理中に内部で使われるもので、webapplication から使われることはありません。

GetVariable

native final function string GetVariable(string VariableName, optional string DefaultValue)

リクエスト変数の値を取得します。リクエスト変数が存在しない場合は、デフォルト値を返します。変数名では、大文字と小文字が区別されます。同名の変数を複数受け取った場合、値を 1 つだけ返します。各変数の値を得るには、 GetVariableNumber と GetVariableCount を使います。

GetVariableCount

native final function int GetVariableCount(string VariableName)

指定されたリクエスト変数の数を返します。値が 1 より大きい場合、 GetVariableNumber を使って個々の値を取得する必要があります。

GetVariableNumber

native final function string GetVariableNumber(string VariableName, int Number, optional string DefaultValue)

指定されたリクエスト変数の値を返します。変数が存在しない場合、または指定された数の変数が存在しない場合は、デフォルト値が返されます。

GetVariables

native final function GetVariables(out array varNames)

受け取ったリクエスト変数の名前を取得します。

WebResponse

フィールド

headers

この配列には、リモートホストに送信されるすべてのヘッダが格納されます。ヘッダが送信されると同時に格納されます。この配列を直接変更することも、 AddHeader 関数を使って変更することもできます。コンテンツの送信時には、このフィールドへの変更は無効になります。

IncludePath

WebServer が送信または処理するファイルが置かれている場所を示す、ベースディレクトリからの相対パス。

Connection

この応答の送信に使われる WebConnection インスタンス。この変数をデータの書込みに使わないでください。

関数

FileExists

native final function bool FileExists(string Filename)

指定されたファイルが web のインクルードディレクトリに存在する場合は True を返します。 ImageServer クラスなど、静的なファイルサーバーの場合にこれを使い、指定ファイルの存在を確認することで、 WebApplication が「HTTP 404 Not Found」エラーを返すようにすることができます。

Subst

native final function Subst(string Variable, coerce string Value, optional bool bClear)

IncludeUHTM と LoadParsedUHTM 関数の実行中に使われる置換変数の値を変更します。3 番目の引数はオプションで、以前に宣言した変数を消去する場合に使います。

ClearSubst

native final function ClearSubst()

登録済みの置換変数をすべて消去します。

IncludeUHTM

native final function bool   IncludeUHTM(string Filename)

UHTM ファイルを読み込んで処理します。処理の結果は直接リモートホストに送信されます。この関数は、ファイルが適切に読み込まれて処理された場合に True を返します。指定するファイルは、 IncludePath フィールドにより宣言されるサブツリーの下に置く必要があります。

IncludeBinaryFile

native final function bool   IncludeBinaryFile(string Filename)

ファイルをリモートホストにそのままの状態で送信します。 IncludeUHTM と異なり、この関数は応答ヘッダが送信されたかどうかの確認を行いません。そのため、このメソッドを呼び出す前にヘッダ送信を確認してください。

LoadParsedUHTM

native final function string LoadParsedUHTM(string Filename)

IncludeUHTM 関数と似ていますが、処理したファイルを返すだけで、リモートホストに送信しない点が大きく異なります。これを使ってより複雑な UHTM テンプレートを作成できます。

GetHTTPExpiration

native final function string GetHTTPExpiration(optional int OffsetSeconds)

現在の日付 + OffsetSeconds から、RFC 1123 に準拠する日付を作成します。これは Expires 応答ヘッダを作成するのに使います。

SendText

event SendText(string Text, optional bool bNoCRLF)

テキストデータの文字列をリモートホストに送信します。 bNoCRLF が True の場合、DOS の行区切り (0x13 0x10) は追加されません。この関数では、テキストデータの送信前に必ず応答ヘッダが送信されます。

SendBinary

event SendBinary(int Count, byte B[255])

バイナリデータをリモートホストに送信します。この関数は、ヘッダ送信の確認を行いません。

HTTPResponse

function HTTPResponse(string Header)

HTTP 応答コードを送信します。デフォルトでは「200 OK」応答が送信されますが、この関数によって代替の応答を送信できます。HTTP 応答コードの詳細は、HTTP RFC を参照してください。HTTP 応答は、header 引数として含める必要があります。以下に例を示します。

HTTPResponse("HTTP/1.0 404 Not Found");

HTTPHeader

function HTTPHeader(string Header)

応答ヘッダを送信します。この関数は、HTTP 応答コードがヘッダの送信前に送信されたかどうかを確認します。ヘッダを送信するのにこのメソッドを呼び出さないでください。ヘッダは、 AddHeader 関数を使うか、または直接 Headers フィールドを編集して配列にいれる方が適しています。

AddHeader

function AddHeader(string header, optional bool bReplace=true)

ヘッダリストにヘッダを追加/更新します。最初に送信可能な時点で送信されます。指定ヘッダを完全に消去するには。"X-Header:" のように空の値を含めます。

同じ名前を持つヘッダを複数追加するには (Set-Cookie ヘッダなどに必要です)、ヘッダ配列を直接編集する必要があります。

SendHeaders

function SendHeaders()

キューに置かれているヘッダを送信します。この関数は SendStandardHeaders が内部で呼び出します。この関数を使用しないでください。

HTTPError

function HTTPError(int ErrorNum, optional string Data)

頻繁に返される HTTP 応答 (400 Bad Request、401 Unauthorized、404 Not Found など) を送信する簡略メソッド。

エラーメッセージと、インラインの HTTP 応答を含めます。大抵このような応答は、ユーザーに分かりやすいような応答を使って各自で処理することをお勧めします。これは便宜上のメソッドです。

SendStandardHeaders

function SendStandardHeaders( optional string ContentType, optional bool bCache )

標準ヘッダとすべてのカスタムヘッダを送信します。この関数を呼び出した後で、安全に応答データを読み込むことができます。

ContentType 引数は、"Content-Type" 応答ヘッダを設定するのに使います。デフォルトの値は "text/html" です。

bCache が True の場合は、キャッシュに関する指図を含むヘッダも含めます。その場合には、 WebServer.ExpirationSeconds の値が使用されます。

"Connection: Close" ヘッダだけが強制実行され、その他のデフォルトヘッダについては、まだ設定されていない場合のみ使用されます。

Redirect

function Redirect(string URL)

「302 Document Moved」HTTP 応答メッセージを送り、クライアントを別の URL にリダイレクトする便利なメソッド。

SentText

function bool SentText()

応答データが送信済みの場合は True。この時点では、ヘッダを送信できなくなります。

SentResponse

function bool SentResponse()

HTTP 応答コードが送信済みの場合は True。この後は、応答 コードを変更できません。ヘッダの送信は続けることができます。

WebServer

このクラスはサブクラス化されることはないので、注目に値する要素のみ紹介します。

フィールド

ServerName

このオプション設定フィールドを使い、WebServer にホスト名を割り当てることができます。サーバーの動作への影響はなく、 ServerURL フィールドの値を、ローカル IP ではなくこの名前に更新するだけです。

Applications

読み込む webapplication の完全修飾クラス名。この変数は ApplicationPaths フィールドと緊密に関係しています。最高 10 の webapplication を定義できます。

ApplicationPaths

webapplication に関連付けるパス。指定順序が大切で、最初に一致するパスが優先権を得ます。

bEnabled

この構成可能フィールドを使い、WebServer を簡単に有効/無効にすることができます。

ListenPort

WebServer がリッスンするポートを定義します。WebServer はバインド先としてこのポートだけ認めます。

MaxConnections

WebServer がサポートする最大同時接続数。この値を非常に高く設定するとゲームのパフォーマンスに影響を及ぼすので、そのように設定しないでください。

DefaultApplication

デフォルトで使用する webapplication。Applications フィールドのインデックスです。要求された URL に対応する webapplication が見つからない場合、ユーザーはこの webapplication に転送されます。このフィールドは、 WebConnection クラスが使用します。

ExpirationSeconds

期限切れ時間を定義するための汎用的な場所を提供する構成可能フィールド。WebReponse クラスで、キャッシュに送られる可能性のある応答の期限を設定するのに用いられます。

ServerURL

このフィールドには、WebServer の起動時に値が挿入されます。WebServer のベース URL を格納します。

関数

GetApplication

function WebApplication GetApplication(string URI, out string SubURI)

このメソッドは、指定 URI に対応する webapplication を返します。このメソッドの 2 番目の引数には、webapplication のパスの接頭辞を外した URI を含めます。

WebConnection

このクラスはサブクラス化されることはないので、注目に値する要素のみ紹介します。

フィールド

MaxValueLength

この構成可能な項目では、リクエスト値に許容する最大長さを定義します。値はこの長さに切り捨てられます。この値は、リクエストを処理するのに十分な長さにする必要があります。 WebRequest クラスがこの値を使用します。

MaxLineLength

リクエストの 1 行の最大長さ。これにより、GET リクエスト内の変数 ('?' に続くテキスト) の長さが制限されるだけでなく、POST データ内の 1 行の長さも制限されます。