SDL_net 3.0 API (アルファベット順)

概要

SDL_netはネットワーキングを支援するためのシンプルなライブラリである.

今日では, これはBSDソケットやWinSockのようなシステムレベルAPIの比較的薄いレイヤーである. このライブラリの利点は, インターフェースが簡略化されており, 予期しない特殊なケースを扱っているためアプリケーションがその処理を行う必要がないことにある.

SDL_netの設計思想は次のようである:

• ブロックしない (しかし, 望むならば明示的に待つことができる)
• アドレッシングが抽象化されており, 特定のネットワークやプロトコルの意識しなくてもよい
• 複雑なものよりもシンプルなものの方がよい. そして, そうだからといって非力でもない

このライブラリはいくつかの要素で構成されており, ほとんどのアプリケーションは全てを使うことはなく, 必要なものを選択して使用することになる.

全てのアプリケーションは, 開始時にNET_Init()を呼び, 終了時にNET_Quit()を呼ぶ必要がある.

このライブラリの基本はNET_Addressオブジェクトである. これが, どのようにネットワークを介して他のコンピュータに到達するか, そのためにどのネットワークプロトコルを使用するかを管理する. NET_Addressはネットワーク越しの対話で必要となる. ホスト名("google.com"や"libsdl.org"のような)をNET_Addressに変換したい場合, NET_ResolveHostname()を呼ぶと背後のスレッドが適切なDNSに問い合わせる. 準備が整うと, NET_Addressを使用してインターネット越しにそのホストに接続できる.

リモートシステムに接続する準備を行った側を「クライアント」と呼び, 接続先を「サーバ」と呼ぶ. 接続を確立するには, 解決したNET_AddressをNET_CreateClient()で使用する. 接続が成立すると(非ブロッキング操作), NET_StreamSocketオブジェクトが得られる. これで接続先とデータの送信と受信をNET_WriteToStreamSocket()とNET_ReadFromStreamSocket()を使用して行える.

クライアントが接続に来るサーバ側になるには, NET_CreateServer()を呼びNET_Serverオブジェクトを得る. NET_Serverが行うことはクライアントの接続を受け入れることだけで, それらをNET_StreamSocketに変換すると, 接続したクライアント側との読み込みと書き込みができるようになる.

このAPIの内部はTCP接続であり, SDL_netを全く使用していないクライアントやサーバとも通信できる.

クライアントとサーバは信頼性の高いバイトストリームである「ストリームソケット」を扱う. これを使用する場合は, 特に通信状態が悪い場合はトレードオフが発生する. 別の選択肢として, UDPパケット転送にマッピングされた「データグラムソケット」が存在する. データグラムではデータの小さなパケットを送信し, 異なる順序で到着することや到着しない場合があるが, パケットが失われても転送は継続し, それぞれのパケットは明確に分離されて, またクライアント・サーバではなくピア・トゥー・ピアでの通信が可能である. データグラムはより複雑になりうるが, これはストリームソケットにはない有用な特性である. NET_CreateDatagramSocket()を使用してデータグラム通信の準備し, NET_SendDatagram()とNET_ReceiveDatagram()でパケットを転送する.

先に言及した通り, SDL_netのAPIは「非ブロッキング」(非同期)である. ネットワークの操作には時間がかかる場合があるが, SDL_netは完了まで待つことはない. 操作からは即座に戻るが, 後でその操作が完了したかチェックできる. 一般的には, これはビデオゲームに求められるが, 操作が完了するまで待つ方がよい場合もある. バックグラウンドスレッドで行えば劇的にコードを単純にできる可能性があり, この方が合理的な場合もある.

これらの関数は操作が完了するまでブロックする.

• NET_WaitUntilConnected
• NET_WaitUntilInputAvailable
• NET_WaitUntilResolved
• NET_WaitUntilStreamSocketDrained

これらの関数にはタイムアウトがあり, 最大待ち時間や, ブロックせずに問い合わせることや, 無限に待つことができる.

最後に, SDL_netはネットワークの問題をシミュレートする方法も提供しており, 理想的ではない現実の通信状態のテストを行える. これで仮にギガビット光通信に有線で直接接続していたとしても, 不安定なwifi接続の場合のようなアプリケーションの挙動をプログラム上で作り出すことができる. これらの関数を使用する:

• NET_SimulateAddressResolutionLoss
• NET_SimulateStreamPacketLoss
• NET_SimulateDatagramPacketLoss

関数

1. NET_AcceptClient - 次の保留中のクライアント接続のストリームソケットを生成する
2. NET_CompareAddresses - 2つのNET_Addressを比較する
3. NET_CreateClient - クライアントとしてリモートサーバにソケット接続を開始する
4. NET_CreateDatagramSocket - データクラムソケットを生成しバインドする
5. NET_CreateServer - 接続をacceptするためにlistenするサーバを生成する
6. NET_DestroyDatagram - 以前に受信したデータグラムパケットを破棄する
7. NET_DestroyDatagramSocket - 以前生成したデータグラムソケットを破棄する
8. NET_DestroyServer - 生成したサーバを破棄する
9. NET_DestroyStreamSocket - 以前生成したストリームソケットを破棄する
10. NET_FreeLocalAddresses - NET_GetLocalAddressesの結果を解放する
11. NET_GetAddressBytes - 解決したアドレスからネットワークアドレスのプロトコルレベルのバイト列を得る
12. NET_GetAddressStatus - ブロックせずにアドレスが解決したかチェックする
13. NET_GetAddressString - 解決したアドレスから人が読める文字列を得る
14. NET_GetConnectionStatus - ブロックせずにソケットが接続したかチェックする
15. NET_GetLocalAddresses - システムのローカルアドレスの一覧を得る
16. NET_GetStreamSocketAddress - ストリームソケットのリモートアドレスを得る
17. NET_GetStreamSocketPendingWrites - ストリームソケットの未送信のバイト数を得る
18. NET_Init - SDL_netライブラリを初期化する
19. NET_Quit - SDL_netライブラリを終了する
20. NET_ReadFromStreamSocket - リモートシステムからストリームソケットに送られたバイトを受信する
21. NET_ReceiveDatagram - リモートシステムからデータグラムソケットに送られた新しいパケットを受信する
22. NET_RefAddress - NET_Addressに参照を追加する
23. NET_ResolveHostname - 人が読めるホスト名を解決する
24. NET_SendDatagram - リモートシステムにデータグラムソケットを通して新しいパケットを送信する
25. NET_SimulateAddressResolutionLoss - アドレス解決の失敗のシミュレートを有効にする
26. NET_SimulateDatagramPacketLoss
27. NET_SimulateStreamPacketLoss
28. NET_UnrefAddress - NET_Addressの参照を切り離す
29. NET_Version - 動的リンクされたSDL_mixerライブラリのバージョンを得る
30. NET_WaitUntilConnected - ストリームソケットがサーバと接続するまで待つ
31. NET_WaitUntilInputAvailable - 複数のソケットの少なくとも1つのデータが利用可能になるまでブロックする
32. NET_WaitUntilResolved - アドレスが解決するまで待つ
33. NET_WaitUntilStreamSocketDrained - ストリームソケットの未送信データの送信が完了するまでブロックする
34. NET_WriteToStreamSocket - リモートシステムにストリームソケットでバイトを送信する

型

1. NET_Address - コンピュータが読むことができるネットワークアドレスを表す不透明型
2. NET_DatagramSocket - 他のシステムへのデータグラム接続を表すオブジェクトの型
3. NET_Server - ストリーム接続の受信側の型
4. NET_StreamSocket - 別システムへのストリーミング接続を表すオブジェクトの型

構造体

1. NET_Datagram - NET_ReceiveDatagram()で受信した新しく到着したパケットのデータの構造体

列挙体

1. NET_Status - 非同期操作の3状態の列挙体

マクロ

1. SDL_NET_MAJOR_VERSION - SDL_netヘッダのメジャーバージョンのマクロ
2. SDL_NET_MICRO_VERSION - SDL_netヘッダのマイクロ(またはパッチレベル)バージョンのマクロ
3. SDL_NET_MINOR_VERSION - SDL_netヘッダのマイナーバージョンのマクロ
4. SDL_NET_VERSION - SDL_netヘッダのバージョンマクロ
5. SDL_NET_VERSION_ATLEAST - 少なくともX.Y.ZのバージョンのSDL_netでコンパイルされたとき真と評価するマクロ

SDL Wikiへのリンク