TWL-DWC 関数リファレンスマニュアル
(日本語版)
TWL-DWC 5.3 patch1 対応
[注意] このドキュメントの内容は、秘密情報であるため、厳重な取扱い、管理を行なってください。
©2005-2009 Nintendo Co.,Ltd. All rights reserved.
Microsoft Internet Explorer 5.0/Netscape 6.0以降推奨
変更履歴
関数リファレンスの変更履歴(ライブラリの変更履歴は、同梱のChangelog.txtを参照下さい)
目次
はじめに
TWL-DWCを使うことで、ニンテンドーDSのワイヤレス通信(インフラストラクチャーモード)を利用してインターネットに接続し、友達を登録したり、友達の状態を参照したり、条件にあった他のニンテンドーDSと接続することができます。
※ TWL-DWC-DLはTWL-DWCから、内部でGamespy社のライブラリを使用しない機能のみを抜き出したものです。TWL-DWC-DLで開発可能なタイトルは、TWL-DWCではなく、必ずTWL-DWC-DLを使用する必要があります。
注意事項
- このパッケージには、本関数リファレンスマニュアルにない関数等が含まれていますが、これらは使用しないでください。
- このパッケージには、ソースの含まれないバイナリが含まれています。
TWL-DWCは、下記の機能を定型的に処理するためにまとめたものです。
- 無線アクセスポイントへの接続のための設定機能
- 無線アクセスポイントからのIPアドレス取得
- 任天堂認証サーバを使用した認証
- ユーザ名・パスワードをゲームユーザが意識する必要のない、ユーザ管理システム
- インターネットに接続したことがあるかどうかをゲームユーザが意識する必要のない、友達登録システム
- 不特定多数を相手とした接続順を意識しない自動的なスター/メッシュ/ハイブリッド(スターとメッシュの混在)型接続作成
- 友達に限定した接続順を意識しない自動的なスター/メッシュ/ハイブリッド(スターとメッシュの混在)型接続作成
- 友達に限定したサーバクライアント方式での半自動的なスター/メッシュ/ハイブリッド(スターとメッシュの混在)型接続作成
- 汎用ランキング機能
- サービスロケータ機能 (独自サーバ利用機能)
- ダウンロード機能(Wi-Fiダウンロードサービス)
- 不正文字列チェック機能
TWL-DWC-DLでは、このうちの下記の機能のみ使用できます。
- 無線アクセスポイントへの接続のための設定機能
- 無線アクセスポイントからのIPアドレス取得
- 任天堂認証サーバを使用した認証
- ダウンロード機能(Wi-Fiダウンロードサービス)
- サービスロケータ機能 (独自サーバ利用機能)
- 不正文字列チェック機能
TWLDWC_ROOT 環境変数に、TwlDWC へのパスを設定してください。
- TWL-DWC[-DL]を使用する場合は、任天堂認証サーバやGameSpyサーバなどのインターネット上のサーバに接続する必要がありますので、アクセスポイントを使ってインターネットに接続できる環境が必須となります。
- インターネットに接続する設定は、本体設定か、Wi-Fiコネクション設定を使用してください。
NITRO-DWCからの移行
TWL-DWCに含まれるマッチメイク機能は、NITRO-DWCに実装されていたものと互換性はありません。
NITRO-DWCのものと比べて、大まかに以下の機能が追加されています。
- マッチメイク開始時に決めた最大人数に達しなくても、マッチメイクを締め切ることができます。また、そのグループを維持したまま、
募集を再開することもできます。
-
接続形態として、全ホストが直接相互に接続しているフルメッシュ型、サーバホストを介して接続しているスター型、スター型とフルメッシュ型の混在(ハイブリッド)の3タイプが選べます。
ハイブリッド接続では、あるグループに接続(マッチメイク完了)した時点では、そのグループのサーバホストとのみ相互接続が確立されていますが、マッチメイク完了後、バックグラウンドでクライアントホスト間の相互接続が構築されていきます。
-
グループを指定して接続することができ、たとえば1度抜けてしまったグループに再接続したり、友達が参加しているグループに接続するといったことが可能です。
詳細は、本パッケージに付属の、Nintendo_WiFi_Connection_TWL-DWC_ProgrammingManual.pdf 及び、関数リファレンスを参照下さい。
TWL-DWCに含まれるダウンロード機能は、NITRO-DWCに実装されていたものから仕様変更になった部分がありますので注意してください。
詳細は、本パッケージに付属の、Nintendo_WiFi_Connection_TWL-DWC_ProgrammingManual_Download.pdf 及び、関数リファレンスを参照下さい。
TWL-DWCで新しく追加された libdwcnonport.*.aライブラリ は必ずリンクする必要があります。
サーバ情報
● 任天堂接続テスト用サーバ
ニンテンドーDSが、現在インターネットに接続可能な環境にあるかどうかを確認する為のサーバです。無停止で運用しております。
稼働状況の確認は、下記のリンクを参照し、「This is test.html page」という文字列が表示されれば稼動中と判断出来ます。
● 任天堂認証サーバ
ニンテンドーDSに設定されたユーザID(Wi-Fi Connection ID)を認証し、GameSpyサーバに接続する為の情報を発行するサーバです。
不正文字列チェックもこのサーバを使用します。
認証サーバは、以下の2種類のものを提供しています。開発・デバッグ時には開発向け認証サーバを使用し、最終ROM作成時に製品向け認証サーバに切り替えてご利用下さい。 開発向け認証サーバ、製品向け認証サーバともに無停止で運用しておりますが、開発向け認証サーバは冗長構成をとっていないため、停止する恐れがあります。万一開発向け認証サーバが停止している場合は、製品向け認証サーバをご利用いただいても問題ありません。認証サーバの選択は、DWC初期化関数DWC_InitForDevelopment/DWC_InitForProductionのどちらを使用するかによって行います。DS-MRCまたはTWLマスターエディタにて"DEBUG "プレフィックス付きのDWCライブラリバージョンが表示されていた場合は、開発向けサーバに接続している可能性があり、最終ROMとして提出することはできませんので注意して下さい。
稼働状況の確認は、下記のリンクを参照し、「AuthServer is up」という文字列が表示されれば稼動中と判断出来ます。
● GameSpyサーバ
友達管理やマッチメイク処理、データストレージサーバ、汎用ランキングで使用するサーバです。
日本時間で毎週火曜日の16時から18時まで停止いたします。時によっては18時でメンテナンスが完了せず、少々長引く場合もあります。
友達管理やマッチメイク処理、データストレージサーバは開発向けと製品向けサーバの区別がないことに注意してください。開発向けと製品向けサーバの区別がないため、リマスター版やローカライズ版の開発でマッチメイクのテストを行なう際に、DWC_InitForDevelopment関数で開発向け認証サーバに設定していても、既に一般市場で発売しているタイトルとマッチメイクしてしまう可能性があります。
これを避けるには、友達無指定ピアマッチメイクで指定できるマッチメイクの候補として検索するプレイヤーの条件によって「製品版」と「デバッグ・開発版」をマッチメイクしないように区別する必要があります。
汎用ランキングについては、認証サーバ同様、開発向けと製品向けの2種類が提供され、認証サーバの切り替えにあわせて切り替えられます。
以下の URL にアクセスすることで、サーバの状態を確認することができます。自動的にサーバをチェックするような仕組みではないため、若干のタイムラグがあります。
このサイトを閲覧するにはNWCWMSへのアクセス許可を得る必要があります。(ID/パスワードは必要ありません。IPアドレスの登録のみ必要となります。)
https://nwcwms.nintendo.co.jp/mtblogs/nwcserverstatus/
● 任天堂ダウンロードサーバ
Wi-Fiダウンロードサービスで使用するサーバです。詳しくは、「Nintendo Wi-Fi Connection TWL-DWC プログラミングマニュアル - ダウンロード編 -」をご確認ください。
認証サーバ同様、開発向けと製品向けの2種類が提供され、認証サーバの切り替えにあわせて切り替えられます。
※ 現在、ダウンロードサーバの稼働状況を確認する方法はありません。
● 備考
- 認証サーバに一度作成したユーザIDを変更・削除することはできません。
- デバッグ用にローカルで使用できるサーバは提供しておりません。
ライセンスについて
- 自動接続処理の一部において、VeriSign社等のルート証明書が組み込まれています。ライセンスの関係上、これを他の目的で利用したり、加工したりはしないで下さい。
- サンプルデモに動作確認用のフォントが含まれています。ライセンスの関係上、これを他の目的で利用したり、加工して利用しないでください。
WEPキーについて
- ニンテンドーDSが対応している暗号化方式はWEPキーを使うものだけです。アクセスポイントが使用する暗号化方式がそれ以外の場合は、アクセスポイント側の暗号化方式を変更する必要があります。
- 通常、アクセスポイントには、WEPキーを4つまで登録できます。ニンテンドーDSの接続先設定には、4つのうち一番目に登録されたWEPキーを入力し、アクセスポイント側も、そのWEPキーを使うように設定します。
- WEPキーの入力は、ASCII文字と呼ばれる英数字を入力する方法と、16進数と呼ばれる0〜9とa〜fを入力する方法があります。
- 入力できるWEPキーの文字数は次の通りです。
ASCII文字の場合…5、13、16文字のいずれか/16進数の場合…10、26、32文字のいずれか
※ ニンテンドーDSiでは、WPAに対応しました。接続先設定4〜6番の上級者設定で設定することが可能です。
$TWLDWC_ROOT/docs/ に次のプログラミングに関するドキュメントが含まれます。
- Nintendo Wi-Fi Connection TWL-DWC プログラミングマニュアル
- Nintendo Wi-Fi Connection TWL-DWC プログラミングマニュアル - 汎用ランキング編 -
※ TWL-DWC-DL には含まれません。
- Nintendo Wi-Fi Connection TWL-DWC プログラミングマニュアル - ダウンロード編 -
- Nintendo Wi-Fi Connection 独自ゲームサーバ利用説明書
その他、制作する際の注意事項を記載した「Nitendo Wi-Fi Connection プログラミングガイドライン for DS」等のドキュメントや、パッケージに含まれるドキュメントの最新版は弊社サポートページより入手してください。
$TWLDWC_ROOT/data/Wi-Fi_icons/ にニンテンドーWi-Fiコネクション対応タイトルで使用する「Wi-Fiコネクション対応アイコン」と「Wi-Fi受信強度アイコン」のビットマップデータとTWL-CHARACTERデータが含まれます。
各アイコンの適用方法については、「Nitendo Wi-Fi Connection プログラミングガイドライン」をご確認ください。
$TWLDWC_ROOT/build/demos/ に実装の参考としてサンプルデモが含まれます。
次の点を留意してください。
- 機能のサンプルを目的としているため、各ガイドラインに則した実装になっていません。
- パッケージの種類によって含まれないものがあります。
$TWLDWC_ROOT/build/demos/dbs/ はサンプルデモ共通で使用するライブラリですので、各サンプルデモをビルドする前にビルドしておく必要があります。
各サンプルデモは、以下の目的で作成されています。
| サンプル名 |
概要 |
TWL-DWC |
TWL-DWC-DL |
| dwc_sample |
TWL-DWCの機能を網羅的に使用したサンプルです |
○ |
|
| dwc_connect_inet_sample |
インターネット接続や接続確認についての単純なサンプルです |
○ |
○ |
| dwc_userdata_sample |
ユーザデータの扱いについてのサンプルです |
○ |
|
| dwc_frienddata_sample |
友達情報の扱いについてのサンプルです |
○ |
|
| dwc_anybody_match_sample |
不特定多数を相手とした接続順を意識しない自動的なハイブリッド(スターとメッシュの混在)型接続作成についてのサンプルです |
○ |
|
| dwc_friend_match_sample |
友達に限定した接続順を意識しない自動的なハイブリッド(スターとメッシュの混在)型接続作成についてのサンプルです |
○ |
|
| dwc_sc_match_sample |
友達に限定したサーバクライアント方式での半自動的なハイブリッド(スターとメッシュの混在)型接続作成についてのサンプルです |
○ |
|
| dwc_eval_callback_sample |
ピア型マッチメイクにおけるマッチメイク候補プレイヤーの評価についてのサンプルです |
○ |
|
| rank_sample |
汎用ランキング機能についてのサンプルです |
○ |
|
| dwc_naslogin_sample |
任天堂認証サーバへログインするサンプルです |
○ |
○ |
| dwc_nd_sample |
ダウンロード機能(Wi-Fiダウンロードサービス)のサンプルです |
○ |
○ |
| dwc_prof_sample |
不正文字列チェック機能のサンプルです |
○ |
○ |
| dwc_svl_sample |
サービスロケータ情報を取得するサンプルです |
○ |
○ |
変更履歴
関数リファレンスの変更履歴です。用語等の軽微な修正は、特に履歴に反映させていないものもあります。
ライブラリの変更履歴は、同梱のChangelog.txtを参照下さい
- 5.3patch1
-
DWC_CheckProfanityAsync : 全リージョン'A'を指定したときの例で、不正文字を示す結果を修正
- 5.3
-
DWC_CreateUserData : 引数にとっていたgamecodeについて、DWC_InitForDevelopment/DWC_InitForProduction関数で指定するように仕様変更したことに伴い、関連する記述を削除
-
DWC_GetCommonValueString : 引数valueにNULLを指定した場合、keyに対応する文字列の長さを返すように仕様変更したことに対応。
-
DWC_InitInetEx : DWC_SetAuthServer関数の廃止に伴い、関連する記述を削除
-
DWC_InitForDevelopment : 関数の仕様変更で、開発用・製品用サーバ用それぞれに初期化関数が分かれたこと、及びゲーム名、イニシャルコード、アロケータの指定が必要になったことに対応
-
DWC_InitForProduction : 関数の仕様変更で、開発用・製品用サーバ用それぞれに初期化関数が分かれたこと、及びゲーム名、イニシャルコード、アロケータの指定が必要になったことに対応
-
DWC_Debug_DWCInitError : DWC_Init関数が、開発用・製品用サーバ用それぞれに分かれたことに対応
-
DWC_InitFriendsMatch : 引数dwccnt,gameNameの廃止に対応。※GameSpyを使用する場合、gameNameはDWC_InitForDevelopment/DWC_InitForProduction関数で指定する必要があります。
-
DWC_ConnectToAnybodyAsync : 認証サーバの切り替えを、DWC_SetAuthServer関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWCAllocEx : TWLモードで動作させた場合の注意について、廃止されたDWC_SetMemFunc関数からこちらに説明を移動
-
DWC_Alloc : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_AllocEx : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_Free : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_Realloc : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_ReallocEx : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_NdInitAsync : 認証サーバの切り替えを、DWC_SetAuthServer関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_RnkInitialize : 認証サーバの切り替えを、DWC_SetAuthServer関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_SVLGetTokenAsync : アロケータの設定をDWC_SetMemFunc関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
-
DWC_StartUtility : 認証サーバの切り替えを、DWC_SetAuthServer関数ではなくDWC_InitForDevelopment/DWC_InitForProduction関数で行うよう仕様変更したため、関連する記述を修正
- 5.3pr1
-
DWC_Alloc : 内部管理用のヘッダの存在に関して返り値及び説明部分を修正
-
DWC_AllocEx : 内部管理用のヘッダの存在に関して返り値及び説明部分を修正
-
DWC_Realloc : 内部管理用のヘッダの存在に関して返り値の説明を修正
-
DWC_ReallocEx : 内部管理用のヘッダの存在に関して返り値の説明を修正
- 5.2
-
DWC_GetLastErrorEx : 無効なリンクを削除
-
DWC_UpdateServersAsync : 友達リストの同期処理中にDWC_CloseAllConnectionsHard関数やDWC_ShutdownFriendsMatch関数を呼べない旨を追記
-
DWC_SetReportLevel : デバックプリントの種別によりゲームに遅延が発生する恐れがあることを追記
-
DWCReportFlag : デバッグ情報出力用フラグに関する説明を追加しました。
- 5.2pr1
-
DWC_GetLastErrorEx : 意味のないアスタリスク(※)を削除
-
DWCInetAuthType : DWC_CONNECTINET_AUTH_DEVELOP,DWC_CONNECTINET_AUTH_RELEASEの説明が間違っていたので修正
-
DWCRnkRegion : 中国の定義名を修正。旧定義も残されています。
- 5.1patch1
-
DWCLoginCallback : 用語統一のため「プロファイルID」を「GSプロファイルID」に変更
-
DWC_CheckProfanityAsync : テスト用の不正文字列がリージョンの区別がなくなったことに対応。
- 5.1
-
DWCApInfo : Wayport(北米ホットスポット)が現在は使用できないことについて追記
-
DWC_SetRwinSize : TWLモードでのみ有効な旨を追記。MTUとの関連性について追記。
-
DWC_ConnectInetAsync : 「接続中に発生したエラー処理を…」を「自動接続処理中に発生した…」に修正
-
DWC_DebugConnectInetAsync : 「接続中に発生したエラー処理を…」を「自動接続処理中に発生した…」に修正
-
DWC_ProcessInet : 「接続中に発生したエラー処理を…」を「自動接続処理中に発生した…」に修正
-
DWC_GetLastErrorEx : Wayport(北米ホットスポット)が現在は使用できないことについて追記
-
DWC_InitForDevelopment : DWC_Init関数の使用前に呼ばなければいけない関数は、OS_Init関数だけである点について修正して記載
-
DWC_InitForProduction : DWC_Init関数の使用前に呼ばなければいけない関数は、OS_Init関数だけである点について修正して記載
-
DWC_LoginAsync : 誤って記載されていた情報を削除(SOライブラリ、DNSキャッシュ)
-
DWCEvalPlayerCallback : 評価値は順番に依存して選ばれやすさが決まることを追記
-
DWC_CheckProfanityAsync : 北米/欧州リージョンのテスト用不正文字列を追記
-
DWC_SetSendDrop : Reliable通信には対応していない旨を追記。
-
DWC_SetRecvDrop : Reliable通信には対応していない旨を追記。
-
DWCApInfoType : Wayport(北米ホットスポット)が現在は使用できないことについて追記
- 5.1pr2
-
DWCApInfo : 構造体のsecurity,areaメンバの説明に誤植があったので修正
-
DWCRnkGetParam : limitに設定できる範囲の上限が、取得モードがDWC_RNK_GET_MODE_FRIENDSの場合は65(DWC_RNK_FRIENDS_MAX+1)になることについて追記
-
DWCRnkGetParam : 共用体の定義に実際の定義と違う箇所があったので訂正。near→nearbyなど。
-
DWC_DebugConnectInetAsync : 引数wep,wepmodeの説明を修正
-
DWCLoadFromServerCallback : DWC_LoadOwnDataAsync関数の廃止に伴い、DWC_LoadOwnDataAsyncをDWC_LoadOwnPrivateDataAsyncに置換
-
DWC_LoginToStorageServerAsync : DWC_LoadOwnDataAsync関数の廃止に伴い、DWC_LoadOwnDataAsyncをDWC_LoadOwnPrivateDataAsyncに置換
-
DWC_SetStorageServerCallback : DWC_LoadOwnDataAsync関数の廃止に伴い、DWC_LoadOwnDataAsyncをDWC_LoadOwnPrivateDataAsyncに置換
-
DWC_LoadOthersDataAsync : DWC_LoadOwnDataAsync関数の廃止に伴い、DWC_LoadOwnDataAsyncをDWC_LoadOwnPrivateDataAsyncに置換
-
DWC_GetLastError : 返り値の説明にDWC_ERROR_NETWORK_LIGHTを追加
-
DWC_GetLastErrorEx : 返り値の説明にDWC_ERROR_NETWORK_LIGHTを追加 「DSネットワークエラーコードリスト」に関する説明を追加
-
DWCFriendStatusCallback : 本コールバックをセットできる関数について追記
-
DWC_SetFriendStatusCallback : DWC_UpdateServersAsync関数によって、コールバック関数が上書きされる旨を追記
-
DWC_InitFriendsMatch : dwccntに関する記述を修正
-
DWC_LoginAsync : 引数ingamesnの説明で空文字列を指定する場合について、説明を追記
-
DWC_UpdateServersAsync : DWC_SetFriendStatusCallback関数によって、statusCallbackに指定したコールバック関数が上書きされる旨を追記
-
DWC_GetMyAID : DWC_SetupGameServerでサーバとして起動したホストについての説明で、重複した内容を削除
-
DWC_GetAIDList : DWC_SetupGameServerでサーバとして起動したホストについての説明で、重複した内容を削除
-
DWC_GetAIDBitmap : DWC_SetupGameServerでサーバとして起動したホストについての説明で、重複した内容を削除
-
DWC_IsValidAID : 自分のAIDを指定した場合は必ずFALSEを返すことについて追記
-
DWC_GetState : 返値からDWC_STATE_UPDATE_SERVERSを削除
-
DWC_AddMatchKeyInt : 返り値の説明を修正 キーに対応した値の更新についての注意を追加
-
DWC_AddMatchKeyString : 返り値の説明を修正 キーに対応した値の更新についての注意を追加
-
DWC_NASLoginProcess : 処理が終了/中断したときの返り値に関する説明を追加
-
DWC_NdGetFileListNumAsync : タイムアウト処理の必要性について記述
-
DWC_NdGetFileListAsync : タイムアウト処理の必要性について記述
-
DWC_NdGetFileAsync : 引数sizeの説明で"最低128バイト"の記述を削除。タイムアウト処理の必要性について記述
-
DWC_CheckProfanityProcess : 処理が終了したときの返り値に関する説明を追加
-
DWC_RnkResGetRow : orderフィールドに順位が格納される条件を追記
-
DWC_SVLProcess : 返り値の定義名の誤記を修正 処理が終了/中断したときの返り値に関する説明を追加
-
DWCRnkRegion : 中国(DWC_RNK_REGION_CH)を追加
5.1PR2より前の変更履歴はこちら