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