00001 /******************************************************************************* 00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology 00003 released in source code form as part of the SDK installer package. 00004 00005 Commercial License Usage 00006 00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology 00008 may use this file in accordance with the end user license agreement provided 00009 with the software or, alternatively, in accordance with the terms contained in a 00010 written agreement between you and Audiokinetic Inc. 00011 00012 Apache License Usage 00013 00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 00015 "Apache License"); you may not use this file except in compliance with the 00016 Apache License. You may obtain a copy of the Apache License at 00017 http://www.apache.org/licenses/LICENSE-2.0. 00018 00019 Unless required by applicable law or agreed to in writing, software distributed 00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for 00022 the specific language governing permissions and limitations under the License. 00023 00024 Version: <VERSION> Build: <BUILDNUMBER> 00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc. 00026 *******************************************************************************/ 00027 00028 /// \file 00029 /// The main communication interface (between the in-game sound engine and 00030 /// authoring tool). 00031 /// \sa 00032 /// - \ref initialization_comm 00033 /// - \ref termination_comm 00034 00035 #ifndef _AK_COMMUNICATION_H 00036 #define _AK_COMMUNICATION_H 00037 00038 #include <AK/SoundEngine/Common/AkTypes.h> 00039 #include <AK/SoundEngine/Common/AkMemoryMgr.h> 00040 #include <AK/Tools/Common/AkPlatformFuncs.h> 00041 00042 #define AK_COMM_SETTINGS_MAX_STRING_SIZE 64 00043 00044 /// Platform-independent initialization settings of communication module between the Wwise sound engine 00045 /// and authoring tool. 00046 /// \sa 00047 /// - AK::Comm::Init() 00048 struct AkCommSettings 00049 { 00050 AkCommSettings() 00051 { 00052 szAppNetworkName[0] = 0; 00053 } 00054 AkUInt32 uPoolSize; ///< Size of the communication pool, in bytes. 00055 #if defined(AK_USE_NX_HTCS) 00056 AkThreadProperties threadProperties; ///< Communication & Connection threading properties (its default priority is AK_THREAD_PRIORITY_ABOVENORMAL) 00057 #endif 00058 00059 /// Ports used for communication between the Wwise authoring application and your game. 00060 /// All of these ports are opened in the game when Wwise communication is enabled. 00061 /// When using HIO type communication, the ports are in fact channels and they must be 3 00062 /// consecutives channels in the order they are defined in the Port structure. 00063 /// 00064 /// \sa 00065 /// - \ref initialization_comm_ports 00066 /// - AK::Comm::GetDefaultInitSettings() 00067 /// - AK::Comm::Init() 00068 struct Ports 00069 { 00070 /// Constructor 00071 Ports() 00072 : uDiscoveryBroadcast( AK_COMM_DEFAULT_DISCOVERY_PORT ) 00073 #if defined( AK_COMM_NO_DYNAMIC_PORTS ) 00074 , uCommand( AK_COMM_DEFAULT_DISCOVERY_PORT + 1 ) 00075 , uNotification( AK_COMM_DEFAULT_DISCOVERY_PORT + 2 ) 00076 #else 00077 , uCommand( 0 ) 00078 , uNotification( 0 ) 00079 #endif 00080 { 00081 } 00082 00083 /// This is where the authoring application broadcasts "Game Discovery" requests 00084 /// to discover games running on the network. Default value: 24024. 00085 /// 00086 /// \warning Unlike the other ports in this structure, this port cannot be dynamic 00087 /// (cannot be set to 0). Refer to \ref initialization_comm_ports_discovery_broadcast 00088 /// for more details. 00089 AkUInt16 uDiscoveryBroadcast; 00090 00091 /// Used by the "command" channel. 00092 /// \remark Set to 0 to request a dynamic/ephemeral port. 00093 AkUInt16 uCommand; 00094 00095 /// Used by the "notification" channel. 00096 /// \remark Set to 0 to request a dynamic/ephemeral port. 00097 AkUInt16 uNotification; 00098 }; 00099 00100 /// Ports used for communication between the Wwise authoring application and your game. 00101 /// \sa 00102 /// - \ref initialization_comm 00103 /// - AkCommSettings::Ports 00104 /// - AK::Comm::Init() 00105 Ports ports; 00106 00107 /// Tells if the base console communication library should be initialized. 00108 /// If set to false, the game should load/initialize the console's communication library prior to calling this function. 00109 /// Set to false only if your game already use sockets before the sound engine initialization. 00110 /// Some consoles have critical requirements for initialization, see \ref initialization_comm_console_lib 00111 bool bInitSystemLib; 00112 00113 /// Optional name that will be displayed over network remote connection of Wwise. 00114 /// It must be a NULL terminated string. 00115 char szAppNetworkName[AK_COMM_SETTINGS_MAX_STRING_SIZE]; 00116 }; 00117 00118 namespace AK 00119 { 00120 namespace Comm 00121 { 00122 /////////////////////////////////////////////////////////////////////// 00123 /// @name Initialization 00124 //@{ 00125 00126 /// Initializes the communication module. When this is called, and AK::SoundEngine::RenderAudio() 00127 /// is called periodically, you may use the authoring tool to connect to the sound engine. 00128 /// 00129 /// \warning This function must be called after the sound engine and memory manager have 00130 /// been properly initialized. 00131 /// 00132 /// 00133 /// \remark The AkCommSettings structure should be initialized with 00134 /// AK::Comm::GetDefaultInitSettings(). You can then change some of the parameters 00135 /// before calling this function. 00136 /// 00137 /// \return 00138 /// - AK_Success if initialization was successful. 00139 /// - AK_InvalidParameter if one of the settings is invalid. 00140 /// - AK_InsufficientMemory if the specified pool size is too small for initialization. 00141 /// - AK_Fail for other errors. 00142 /// 00143 /// \sa 00144 /// - \ref initialization_comm 00145 /// - AK::Comm::GetDefaultInitSettings() 00146 /// - AkCommSettings::Ports 00147 AK_EXTERNAPIFUNC( AKRESULT, Init )( 00148 const AkCommSettings & in_settings///< Initialization settings. 00149 ); 00150 00151 /// Gets the last error from the OS-specific communication library. 00152 /// \return The system error code. Check the code in the platform manufacturer documentation for details about the error. 00153 AK_EXTERNAPIFUNC(AkInt32, GetLastError()); 00154 00155 /// Gets the communication module's default initialization settings values. 00156 /// \sa 00157 /// - \ref initialization_comm 00158 /// - AK::Comm::Init() 00159 AK_EXTERNAPIFUNC( void, GetDefaultInitSettings )( 00160 AkCommSettings & out_settings ///< Returned default initialization settings. 00161 ); 00162 00163 /// Terminates the communication module. 00164 /// \warning This function must be called before the memory manager is terminated. 00165 /// \sa 00166 /// - \ref termination_comm 00167 AK_EXTERNAPIFUNC( void, Term )(); 00168 00169 /// Terminates and reinitialize the communication module using current settings. 00170 /// 00171 /// \return 00172 /// - AK_Success if initialization was successful. 00173 /// - AK_InvalidParameter if one of the settings is invalid. 00174 /// - AK_InsufficientMemory if the specified pool size is too small for initialization. 00175 /// - AK_Fail for other errors. 00176 /// 00177 /// \sa 00178 /// - \ref AK::SoundEngine::iOS::WakeupFromSuspend() 00179 AK_EXTERNAPIFUNC( AKRESULT, Reset )(); 00180 00181 00182 /// Get the initialization settings currently in use by the CommunicationSystem 00183 /// 00184 /// \return 00185 /// - AK_Success if initialization was successful. 00186 AK_EXTERNAPIFUNC( const AkCommSettings&, GetCurrentSettings )(); 00187 00188 //@} 00189 } 00190 } 00191 00192 #endif // _AK_COMMUNICATION_H