TWL-DWC 関数リファレンスマニュアル
(日本語版)

TWL-DWC 5.3 patch1_sslgdb4 対応

[注意]　このドキュメントの内容は、秘密情報であるため、厳重な取扱い、管理を行なってください。

©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/TWL-DWC-DLの構成

TWL-DWCは、下記の機能を定型的に処理するためにまとめたものです。

TWL-DWC-DLでは、このうちの下記の機能のみ使用できます。

使用方法

注意事項

NITRO-DWCからの移行

TWL-DWCに含まれるマッチメイク機能は、NITRO-DWCに実装されていたものと互換性はありません。 NITRO-DWCのものと比べて、大まかに以下の機能が追加されています。

詳細は、本パッケージに付属の、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サーバに接続する為の情報を発行するサーバです。
不正文字列チェックもこのサーバを使用します。

認証サーバは、以下の２種類のものを提供しています。開発・デバッグ時には開発向け認証サーバを使用し、最終ROM作成時に製品向け認証サーバに切り替えてご利用下さい。 開発向け認証サーバ、製品向け認証サーバともに無停止で運用しておりますが、開発向け認証サーバは冗長構成をとっていないため、停止する恐れがあります。万一開発向け認証サーバが停止している場合は、製品向け認証サーバをご利用いただいても問題ありません。認証サーバの選択は、DWC初期化関数DWC_InitForDevelopment/DWC_InitForProductionのどちらを使用するかによって行います。DS-MRCまたはTWLマスターエディタにて"DEBUG "プレフィックス付きのDWCライブラリバージョンが表示されていた場合は、開発向けサーバに接続している可能性があり、最終ROMとして提出することはできませんので注意して下さい。

稼働状況の確認は、下記のリンクを参照し、「AuthServer is up」という文字列が表示されれば稼動中と判断出来ます。

製品向け認証サーバ 開発向け認証サーバ
● GameSpyサーバ

友達管理やマッチメイク処理、データストレージサーバ、汎用ランキングで使用するサーバです。
日本時間で毎週火曜日の１６時から１８時まで停止いたします。時によっては１８時でメンテナンスが完了せず、少々長引く場合もあります。

友達管理やマッチメイク処理、データストレージサーバは開発向けと製品向けサーバの区別がないことに注意してください。開発向けと製品向けサーバの区別がないため、リマスター版やローカライズ版の開発でマッチメイクのテストを行なう際に、DWC_InitForDevelopment関数で開発向け認証サーバに設定していても、既に一般市場で発売しているタイトルとマッチメイクしてしまう可能性があります。

これを避けるには、友達無指定ピアマッチメイクで指定できるマッチメイクの候補として検索するプレイヤーの条件によって「製品版」と「デバッグ・開発版」をマッチメイクしないように区別する必要があります。

汎用ランキングについては、認証サーバ同様、開発向けと製品向けの２種類が提供され、認証サーバの切り替えにあわせて切り替えられます。

以下の URL にアクセスすることで、サーバの状態を確認することができます。自動的にサーバをチェックするような仕組みではないため、若干のタイムラグがあります。 このサイトを閲覧するにはNWCWMSへのアクセス許可を得る必要があります。(ID/パスワードは必要ありません。IPアドレスの登録のみ必要となります。)
https://nwcwms.nintendo.co.jp/mtblogs/nwcserverstatus/

● 任天堂ダウンロードサーバ

Wi-Fiダウンロードサービスで使用するサーバです。詳しくは、「Nintendo Wi-Fi Connection TWL-DWC プログラミングマニュアル - ダウンロード編 -」をご確認ください。

認証サーバ同様、開発向けと製品向けの２種類が提供され、認証サーバの切り替えにあわせて切り替えられます。

※ 現在、ダウンロードサーバの稼働状況を確認する方法はありません。

● 備考

ライセンスについて

WEPキーについて

※ ニンテンドーDSiでは、WPAに対応しました。接続先設定4〜6番の上級者設定で設定することが可能です。

ドキュメントについて

$TWLDWC_ROOT/docs/ に次のプログラミングに関するドキュメントが含まれます。

その他、制作する際の注意事項を記載した「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/ に実装の参考としてサンプルデモが含まれます。
次の点を留意してください。

各サンプルデモは、以下の目的で作成されています。

サンプル名 概要 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_sslgdb1
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より前の変更履歴はこちら