1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: socket_Common.h 4 5 Copyright (C)2010 Nintendo Co., Ltd. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Rev: 26646 $ 14 *---------------------------------------------------------------------------*/ 15 16 #ifndef NN_SOCKET_SOCKET_COMMON_H_ 17 #define NN_SOCKET_SOCKET_COMMON_H_ 18 19 #include <nn/types.h> 20 #include <nn/os/os_Event.h> 21 #include <nn/fnd/fnd_Allocator.h> 22 #include <nn/socket/socket_Types.h> 23 24 namespace nn { 25 namespace socket { 26 27 namespace { 28 const char PORT_NAME_USER[] = "soc:U"; 29 const char PORT_NAME_PRIVILEGED[] = "soc:P"; 30 } 31 namespace detail{ 32 void* Allocate(size_t size, s32 alignment = sizeof(int)); 33 Result Allocate(void*& p, size_t size, s32 alignment = sizeof(int)); 34 void Free(void* p); 35 } 36 37 /*! 38 @name 初期化・終了 39 40 @{ 41 */ 42 43 /*! 44 @brief ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。 45 46 @param[in] bufferAddress 47 ソケットライブラリが使用するワーク領域のアドレスを指定します。 48 4096 バイト整合である必要があります。デバイスメモリは使用できません。 49 50 @param[in] bufferSize 51 ワーク領域のサイズを指定します。 52 <br/> 53 ワーク領域は最低でも @ref GetRequiredMemorySize で求めたサイズ以上の 54 大きさが必要です。 55 <br/> 56 通常の使用方法であれば、この値をそのまま使用して問題ありませんが、 57 @ref GetAddrInfo で多数の @ref AddrInfo を確保する場合はさらに大きいサイズを必要に応じて指定してください。 58 59 @param[in] bufferSizeForSockets 60 ワーク領域のうち、ソケットの送受信バッファの割り当てに使用するサイズを指定します。 61 <br/> 62 各ソケットの送受信バッファは @ref SetSockOpt にて指定できます。 63 デフォルトでは 1 ソケットあたり TCP では 16KB（送信 8KB・受信 8KB）、UDP では 32KB のメモリを割り当てます。 64 ソケットを 1 つだけ使う場合でも、最低 64KB 程度は確保するようにしてください。 65 <br/> 66 ※デフォルトのバッファサイズは今後変更される可能性があります。 67 68 @param[in] maxSessions ソケット API を扱うスレッド数を指定します。 69 <br/> 70 この値を超えるスレッドからブロックするソケット API を呼ぶことはできません。 71 厳密には同時にブロックする API を呼び出さなければ、 72 この値を超える数のスレッドからソケット API を呼び出すことができますが推奨しません。 73 <br/> 74 API の呼び出し中にセッション数が不足した場合、 75 同期・非同期に関わらず使用できるセッションが空くまでブロックします。 76 また、データの着信や送信の完了などブロックの解除条件が満たされても、セッションが空くまでブロックは解除されません。 77 非同期操作は同期的な挙動になるので特に注意してください。 78 <br/> 79 @ref Poll を使用すると、1 回の API 呼び出しで複数のソケットの状態を確認することができ、 80 ソケット API を扱うスレッド数を減らすことができます。 81 82 @return 処理結果。 83 */ 84 Result Initialize(uptr bufferAddress, size_t bufferSize, s32 bufferSizeForSockets, s32 maxSessions); 85 86 87 /*! 88 @brief ソケットライブラリを初期化に最低限必要なワーク領域のサイズを求めます。 89 90 ワーク領域は @ref GetAddrInfo で返される @ref AddrInfo の確保に使用される他、API の呼び出し中に一時的に使用されます。 91 <br/> 92 ある程度余分にサイズを予約した上で値を計算していますので、通常はワーク領域がいつ使われているかを気にする必要はありません。 93 <br/> 94 ただし、@ref GetAddrInfo で取得した @ref AddrInfo を @ref FreeAddrInfo で解放せずに 95 連続して @ref GetAddrInfo を呼び出すような場合は、返された値よりもさらに大きなメモリが必要になる場合があります。 96 97 @param[in] bufferSizeForSockets 98 @ref Initialize の同名引数に指定する数。 99 100 @param[in] maxSessions @ref Initialize の同名引数に指定する数。 101 102 @return 必要なワーク領域のサイズ。 103 */ 104 size_t GetRequiredMemorySize(size_t bufferSizeForSockets, s32 maxSessions); 105 106 107 /*! 108 @brief ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。 109 110 過去との互換性のために残されています。メモリの使用効率が悪いため、なるべく使用しないでください。 111 */ 112 Result Initialize(nn::fnd::IAllocator& allocator, size_t bufferSize, s32 maxSessions) NN_ATTRIBUTE_DEPRECATED; 113 114 /*! 115 @brief ソケットライブラリを初期化し、ソケット API を呼び出せるようにします。 116 117 パラメータを省略してすべてデフォルト値を指定します。 118 テスト用途のために用意されています。製品の開発には使用しないでください。 119 120 @return 処理結果。 121 */ 122 Result Initialize(void); 123 124 125 /*! 126 @brief ソケットライブラリを終了し、使用していたリソースを解放します。 127 128 使用中のソケット記述子はすべて破棄され、ブロック中の API も全てキャンセルされエラーを返します。 129 130 @return 処理結果。 131 */ 132 Result Finalize(void); 133 134 135 /*! 136 :private 137 @brief ソケットのシステム用 API を呼び出せるようにします。 138 Initialize とは別に呼び出す必要があります。 139 140 使用権限のない一般アプリケーションが呼び出すと常に失敗します。 141 142 @return 処理結果。 143 */ 144 Result InitializePrivilegedControl(void); 145 146 147 /*! 148 :private 149 @brief システム用 API の利用を終了し、使用していたリソースを解放します。 150 151 @return 処理結果。 152 */ 153 Result FinalizePrivilegedControl(void); 154 155 /*! 156 :private 157 @brief ソケットプロセスに動作の開始を指示します。 158 159 ソケットプロセスは動作を開始すると、IP アドレスの取得を試みます。 160 DHCP でアドレスを取得する設定になっている場合は、 161 取得処理が完了するまでブロックします。 162 163 事前に InitializePrivilegedControl の呼び出しが必要です。 164 165 @param[in] config ソケットの設定 166 167 @return 処理結果。 168 */ 169 Result Startup(const Config& config); 170 171 /*! 172 :private 173 @brief ソケットプロセスに動作の停止を指示します。 174 175 ソケットプロセスは動作を停止する際に IP アドレスの開放を試みます。 176 停止が完了すると IP アドレスは 0.0.0.0 となり一切の通信ができません。 177 178 事前に InitializePrivilegedControl の呼び出しが必要です。 179 180 @return 処理結果。 181 */ 182 Result Cleanup(void); 183 /*! 184 @} 185 186 @name そのほか 187 188 @{ 189 */ 190 191 Result CloseAll(void); 192 Result CloseAll(bit32 processId); 193 194 Result SetMaxDescriptor(s32 number); 195 Result AllowOtherProcess(s32 s); 196 197 198 /*! 199 :private 200 @brief ソケットプロセスの内部で発生したエラーを取得します。 201 202 事前に InitializePrivilegedControl の呼び出しが必要です。 203 204 @param[out] err 内部エラーコード 205 206 @return 処理結果。 207 */ 208 Result GetConfigError(s32* err); 209 210 /*! 211 :private 212 @brief ソケットプロセスの内部で発生したエラーを通知するイベントを取得します。 213 214 取得できるイベントは手動リセットイベントです。 215 一度エラーが発生すると再び Startup し直すまでずっとシグナル状態を維持します。 216 217 事前に InitializePrivilegedControl の呼び出しが必要です。 218 219 @param[out] event 通知のためのイベント。 220 未初期化のイベントを渡してください。 221 222 @return 処理結果。 223 */ 224 Result GetErrorReportEvent(nn::os::Event& event); 225 226 /*! 227 @} 228 */ 229 } 230 } 231 232 #endif // ifndef NN_SOCKET_SOCKET_COMMON_H_ 233