Table of Contents

include/AK/Comm/AkCommunication.h

Go to the documentation of this file.
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