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: 32947 $ 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 @param[in] bUseSecondarySession true にすると複数セッションが必要な操作 142 (Startup 中の AbortStartup) が可能になります 143 144 @return 処理結果。 145 */ 146 Result InitializePrivilegedControl(bool bUseSecondarySession = false); 147 148 149 /*! 150 :private 151 @brief システム用 API の利用を終了し、使用していたリソースを解放します。 152 153 @return 処理結果。 154 */ 155 Result FinalizePrivilegedControl(void); 156 157 /*! 158 :private 159 @brief ソケットプロセスに動作の開始を指示します。 160 161 ソケットプロセスは動作を開始すると、IP アドレスの取得を試みます。 162 DHCP でアドレスを取得する設定になっている場合は、 163 取得処理が完了するまでブロックします。 164 165 事前に InitializePrivilegedControl の呼び出しが必要です。 166 167 @param[in] config ソケットの設定 168 169 @return 処理結果。 170 */ 171 Result Startup(const Config& config); 172 173 /*! 174 :private 175 @brief ソケットプロセスに動作の停止を指示します。 176 177 ソケットプロセスは動作を停止する際に IP アドレスの開放を試みます。 178 停止が完了すると IP アドレスは 0.0.0.0 となり一切の通信ができません。 179 180 事前に InitializePrivilegedControl の呼び出しが必要です。 181 182 @return 処理結果。 183 */ 184 Result Cleanup(void); 185 186 /*! 187 :private 188 @brief @ref Startup を中断します。 189 190 @return 処理結果。 191 */ 192 Result AbortStartup(void); 193 194 /*! 195 @} 196 197 @name そのほか 198 199 @{ 200 */ 201 202 Result CloseAll(void); 203 Result CloseAll(bit32 processId); 204 205 Result SetMaxDescriptor(s32 number); 206 Result AllowOtherProcess(s32 s); 207 208 209 /*! 210 :private 211 @brief ソケットプロセスの内部で発生したエラーを取得します。 212 213 事前に InitializePrivilegedControl の呼び出しが必要です。 214 215 @param[out] err 内部エラーコード 216 217 @return 処理結果。 218 */ 219 Result GetConfigError(s32* err); 220 221 /*! 222 :private 223 @brief ソケットプロセスの内部で発生したエラーを通知するイベントを取得します。 224 225 取得できるイベントは手動リセットイベントです。 226 一度エラーが発生すると再び Startup し直すまでずっとシグナル状態を維持します。 227 228 事前に InitializePrivilegedControl の呼び出しが必要です。 229 230 @param[out] event 通知のためのイベント。 231 未初期化のイベントを渡してください。 232 233 @return 処理結果。 234 */ 235 Result GetErrorReportEvent(nn::os::Event& event); 236 237 /*! 238 @} 239 */ 240 } 241 } 242 243 #endif // ifndef NN_SOCKET_SOCKET_COMMON_H_ 244