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 /// Wwise source control plug-in interface, used to implement the source control plug-in. 00030 00031 #ifndef _AK_WWISE_ISOURCECONTROL_H 00032 #define _AK_WWISE_ISOURCECONTROL_H 00033 00034 // Include the header file that defines the BSTR type. 00035 #include <wtypes.h> 00036 00037 #include "ISourceControlUtilities.h" 00038 #include "SourceControlContainers.h" 00039 00040 // Audiokinetic namespace 00041 namespace AK 00042 { 00043 // Audiokinetic Wwise namespace 00044 namespace Wwise 00045 { 00046 /// This class contains static constants that can be useful to the plug-in. 00047 class SourceControlConstant 00048 { 00049 public: 00050 /// Maximum length that a work unit name can be 00051 static const unsigned int s_uiMaxWorkUnitName = 128; 00052 /// Invalid operation ID (MUST NOT BE USED as an operation ID in OperationListItem) 00053 static const DWORD s_dwInvalidOperationID = (DWORD)-1; 00054 }; 00055 00056 /// Wwise source control plug-in interface. This is the interface that the plug-in must implement. It contains 00057 /// all the necessary functions to perform source control operations and manage the Wwise source control UI. 00058 /// \warning The functions in this interface are not thread-safe, unless stated otherwise. 00059 /// \sa 00060 /// - \ref source_control_dll_creation_object_information 00061 class ISourceControl 00062 { 00063 public: 00064 00065 /// \name Enumeration types 00066 //@{ 00067 00068 /// Operation result. Some interface functions need to return the result of the operation. This is used 00069 /// by Wwise to manage various errors. 00070 enum OperationResult 00071 { 00072 OperationResult_Succeed = 0, ///< The operation succeeded 00073 OperationResult_Failed, ///< The operation failed 00074 OperationResult_TimedOut, ///< The operation timed out 00075 OperationResult_NotImplemented ///< The operation is not implemented 00076 }; 00077 00078 /// Menu type. The operation list may vary depending on the location where a menu containing operations 00079 /// needs to be displayed. 00080 enum OperationMenuType 00081 { 00082 OperationMenuType_WorkUnits = 0,///< The menu is displayed in the Workgroup Manager's 'Work Units' tab 00083 OperationMenuType_Sources, ///< The menu is displayed in the Workgroup Manager's 'Sources' tab 00084 OperationMenuType_Explorer ///< The menu is displayed in the Project Explorer 00085 }; 00086 00087 /// Pre/PostCreateOrModify Operation flags. These flags represent the operation(s) performed on files. 00088 enum CreateOrModifyOperation 00089 { 00090 CreateOrModifyOperation_Create = 1 << 0, ///< Files will be created during the operation 00091 CreateOrModifyOperation_Modify = 1 << 1, ///< Files will be modified during the operation 00092 }; 00093 00094 /// The operation's effect on the file(s) involved. 00095 enum OperationEffect 00096 { 00097 OperationEffect_LocalContentModification = 1 << 0, ///< The operation will modify the local content of the file 00098 OperationEffect_ServerContentModification = 1 << 1, ///< The operation will modify the remote content (on the server) of the file 00099 }; 00100 00101 //@} 00102 00103 /// The base interface for operations that return information to Wwise 00104 class IOperationResult 00105 { 00106 public: 00107 /// Returns OperationResult_Succeed or OperationResult_Failed 00108 virtual OperationResult GetOperationResult() = 0; 00109 00110 /// Implementations should call "delete this;". 00111 virtual void Destroy() = 0; 00112 }; 00113 00114 /// The result returned by DoOperation for a Move, Rename or Delete operation 00115 /// A instance of this class is allocated by the plugin and freed by Wwise 00116 /// The operation ID must be identified by : 00117 /// PluginInfo::m_dwMoveCommandID, PluginInfo::m_dwMoveNoUICommandID, 00118 /// PluginInfo::m_dwRenameCommandID or PluginInfo::m_dwRenameNoUICommandID 00119 /// PluginInfo::m_dwDeleteCommandID or PluginInfo::m_dwDeleteNoUICommandID 00120 class IFileOperationResult : public IOperationResult 00121 { 00122 public: 00123 /// Return the move source and destination for the file at index in_uiIndex 00124 virtual void GetMovedFile( 00125 unsigned int in_uiIndex, ///< in: The index of the moved file. Must be >= 0 and < GetFileCount() 00126 LPWSTR out_szFrom, ///< out: String buffer to receive the source path 00127 LPWSTR out_szTo, ///< out: String buffer to receive the destination path 00128 unsigned int in_uiArraySize ///< in: Size of the buffers (out_szFrom and out_szTo) 00129 ) = 0; 00130 00131 /// Return the successful file at index in_uiIndex 00132 virtual void GetFile( 00133 unsigned int in_uiIndex, ///< in: The index of the file. Must be >= 0 and < GetFileCount() 00134 LPWSTR out_szPath, ///< out: String buffer to receive the source path 00135 unsigned int in_uiArraySize ///< in: Size of the buffers (out_szFrom and out_szTo) 00136 ) = 0; 00137 00138 /// Returns how many files were moved during the operation 00139 virtual unsigned int GetFileCount() = 0; 00140 }; 00141 00142 /// 'Filename to Status' map item. This is the type used in the AK::Wwise::ISourceControl::FilenameToStatusMap 00143 /// SourceControlContainers::IAkMap template parameter structure. 00144 struct FilenameToStatusMapItem 00145 { 00146 BSTR m_bstrStatus; ///< Text displayed in the Workgroup Manager's 'Status' column 00147 BSTR m_bstrOwner; ///< Text displayed in the Workgroup Manager's 'Owners' column 00148 }; 00149 00150 /// Operation list item. This is the type used in the AK::Wwise::ISourceControl::OperationList SourceControlContainers::IAkList template class. 00151 struct OperationListItem 00152 { 00153 DWORD m_dwOperationID; ///< The operation ID 00154 bool m_bEnabled; ///< True: the operation is enabled in the menu, False: the operation is disabled (grayed out) in the menu 00155 }; 00156 00157 /// FilenameToIconMap item. This is the type used to display the file status icon and tool tip text 00158 /// in the Project Explorer. 00159 struct FilenameToIconMapItem 00160 { 00161 HICON m_hIcon; ///< A handle to an icon that will be displayed in the Project Explorer 00162 BSTR m_bstrToolTip; ///< The tool tip text that will be displayed when the user mouses over the icon 00163 }; 00164 00165 /// \name List types 00166 //@{ 00167 00168 /// String List. When Wwise needs to pass a file name list, it gives this container to the plug-in. 00169 /// \sa 00170 /// - AK::Wwise::SourceControlContainers::IAkList 00171 typedef SourceControlContainers::IAkList<LPCWSTR, LPCWSTR> StringList; 00172 00173 /// Plug-in ID list. When Wwise needs to have the list of plug-ins that a DLL contains, it requests 00174 /// the list of plug-in IDs using a function exported by the DLL. 00175 typedef SourceControlContainers::IAkList<GUID> PluginIDList; 00176 00177 /// When Wwise needs to have the list of operations that are available in a certain context, it requests 00178 /// the list of operations using this list type. The contexts are determined by the AK::Wwise::ISourceControl::OperationMenuType 00179 /// enumeration type. 00180 /// \sa 00181 /// - AK::Wwise::ISourceControl::OperationListItem 00182 /// - AK::Wwise::SourceControlContainers::IAkList 00183 typedef SourceControlContainers::IAkList<OperationListItem> OperationList; 00184 00185 //@} 00186 00187 /// \name Map types 00188 //@{ 00189 00190 /// The AK:Wwise::ISourceControl interface offers a way to display custom icons in the Project Explorer. This map 00191 /// type must be filled in by the plug-in when Wwise gives it a file name list. CString objects are used as keys, and are associated 00192 /// to FilenameToIconMapItem objects. The HICON m_hIcon member will be NULL when there is no icon associated with the file. 00193 /// \sa 00194 /// - AK::Wwise::SourceControlContainers::IAkMap 00195 typedef SourceControlContainers::IAkMap<LPCWSTR, LPCWSTR, FilenameToIconMapItem, const FilenameToIconMapItem&> FilenameToIconMap; 00196 00197 /// When the Workgroup Manager needs to fill in the 'Status' and 'Owners' columns of work units or source lists, 00198 /// the plug-in needs to fill in this map with the corresponding text. File names are used as keys, and are associated 00199 /// to the text to be displayed in the 'Status' and 'Owners' columns. 00200 /// \sa 00201 /// - AK::Wwise::ISourceControl::FilenameToStatusMapItem 00202 /// - AK::Wwise::SourceControlContainers::IAkMap 00203 typedef SourceControlContainers::IAkMap<LPCWSTR, LPCWSTR, FilenameToStatusMapItem, const FilenameToStatusMapItem&> FilenameToStatusMap; 00204 00205 //@} 00206 00207 /// Plug-in information structure. This structure gives a simple overview of the plug-in's capabilities. 00208 class PluginInfo 00209 { 00210 public: 00211 BSTR m_bstrName; ///< The name of the plug-in displayed in the Project Settings plug-in list 00212 unsigned int m_uiVersion; ///< The current version of the plug-in 00213 00214 bool m_bShowConfigDlgAvailable; ///< Used to enable/disable the 'Config...' button in the Project Settings 00215 DWORD m_dwUpdateCommandID; ///< Indicates the command ID for the Update command, s_dwInvalidOperationID (-1) if not supported 00216 DWORD m_dwCommitCommandID; ///< Indicates the command ID for the Commit/Submit/Checkin command, s_dwInvalidOperationID (-1) if not supported 00217 DWORD m_dwRenameCommandID; ///< Indicates the command ID for the Rename command, s_dwInvalidOperationID (-1) if not supported 00218 DWORD m_dwMoveCommandID; ///< Indicates the command ID for the Move command, s_dwInvalidOperationID (-1) if not supported 00219 DWORD m_dwAddCommandID; ///< Indicates the command ID for the Add command, s_dwInvalidOperationID (-1) if not supported 00220 DWORD m_dwDeleteCommandID; ///< Indicates the command ID for the Delete command, s_dwInvalidOperationID (-1) if not supported 00221 DWORD m_dwRevertCommandID; ///< Indicates the command ID for the Revert command, s_dwInvalidOperationID (-1) if not supported 00222 DWORD m_dwDiffCommandID; ///< Indicates the command ID for the Diff command, s_dwInvalidOperationID (-1) if not supported 00223 DWORD m_dwCheckOutCommandID; ///< Indicates the command ID for the Diff command, s_dwInvalidOperationID (-1) if not supported 00224 DWORD m_dwRenameNoUICommandID; ///< Indicates the command ID for the Rename command, showing no User Interface, s_dwInvalidOperationID (-1) if not supported 00225 DWORD m_dwMoveNoUICommandID; ///< Indicates the command ID for the Move command, showing no User Interface, s_dwInvalidOperationID (-1) if not supported 00226 DWORD m_dwDeleteNoUICommandID; ///< Indicates the command ID for the Delete command, showing no User Interface, s_dwInvalidOperationID (-1) if not supported 00227 bool m_bStatusIconAvailable; ///< Indicates that the plug-in supports Project Explorer custom icons 00228 }; 00229 00230 /// This function is called when the plug-in is initialized after its creation. 00231 virtual void Init( 00232 AK::Wwise::ISourceControlUtilities* in_pUtilities, ///< A pointer to the utilities class. The interface is not 00233 ///< destroyed while an instance of the plug-in exists. 00234 bool in_bAutoAccept ///< Used when running in command line mode, where user should not be prompted to confirm source control transactions. 00235 ) = 0; 00236 00237 /// This function is called when the plug-in is terminated before its destruction. 00238 virtual void Term() = 0; 00239 00240 /// This function destroys the plug-in. The implementation is generally '{ delete this; }'. 00241 virtual void Destroy() = 0; 00242 00243 /// This function is called when the user clicks the 'Config...' button in the Project Settings. 00244 /// \return True if the user accepts the configuration, False otherwise 00245 /// \sa 00246 /// - AK::Wwise::ISourceControl::PluginInfo::m_bShowConfigDlgAvailable 00247 virtual bool ShowConfigDlg() = 0; 00248 00249 /// Gets the operation list to be displayed in a menu. 00250 /// \return The result of the operation 00251 virtual AK::Wwise::ISourceControl::OperationResult GetOperationList( 00252 OperationMenuType in_menuType, ///< The type of menu where the operation list will be displayed 00253 const StringList& in_rFilenameList, ///< The file name list for which Wwise needs to get the operation list 00254 OperationList& out_rOperationList ///< The returned operation list available in this context 00255 ) = 0; 00256 00257 /// Gets the operation name to display in user interface 00258 // \return A mask of all the applicable OperationEffect enum values 00259 virtual LPCWSTR GetOperationName( 00260 DWORD in_dwOperationID ///< The ID of the operation, as specified in OperationListItem 00261 ) = 0; 00262 00263 /// Gets the operation effect on the file(s) involved in the operation. 00264 // \return A mask of all the applicable OperationEffect enum values 00265 virtual DWORD GetOperationEffect( 00266 DWORD in_dwOperationID ///< The ID of the operation, as specified in OperationListItem 00267 ) = 0; 00268 00269 /// Gets the text to be displayed in the 'Status' and 'Owners' columns of the Workgroup Manager. 00270 /// \return The result of the operation 00271 virtual AK::Wwise::ISourceControl::OperationResult GetFileStatus( 00272 const StringList& in_rFilenameList, ///< A list of the file names for which Wwise needs to get the status 00273 FilenameToStatusMap& out_rFileStatusMap,///< The returned 'Filename To Status' map 00274 DWORD in_dwTimeoutMs = INFINITE ///< The maximum timeout in millisecond for the request to be cancelled, pass INFINITE for no timeout 00275 ) = 0; 00276 00277 /// In a similar way to AK::Wwise::ISourceControl::GetFileStatus(), this function gets the icons to be displayed in the 00278 /// Project Explorer. 00279 /// \return The result of the operation 00280 virtual AK::Wwise::ISourceControl::OperationResult GetFileStatusIcons( 00281 const StringList& in_rFilenameList, ///< A list of the file names for which Wwise needs to get the icons 00282 FilenameToIconMap& out_rFileIconsMap, ///< The returned 'Filename To Icons' map 00283 DWORD in_dwTimeoutMs = INFINITE ///< The maximum timeout in millisecond for the request to be cancelled, pass INFINITE for no timeout 00284 ) = 0; 00285 00286 /// Gets the files that should be displayed in the Workgroup Manager file list, but that are not on the local disk. 00287 /// Deleted files that need to be submitted to the server are an example of implementation. 00288 /// \return The result of the operation 00289 virtual AK::Wwise::ISourceControl::OperationResult GetMissingFilesInDirectories( 00290 const StringList& in_rDirectoryList, ///< A list of directories in which Wwise needs to get missing files 00291 StringList& out_rFilenameList ///< The returned missing files 00292 ) = 0; 00293 00294 /// Performs an operation on files. This function is called when the user clicks on a source control operation 00295 /// in a menu. 00296 /// For Rename and Move operations in No-User-Interface mode, in_pTargetFilenameList contains the list of target names are known in advance. 00297 virtual IOperationResult* DoOperation( 00298 DWORD in_dwOperationID, ///< The ID of the operation that the user selected from the menu 00299 const StringList& in_rFilenameList, ///< A list of the names of the files that the user selected in the Workgroup Manager or in the Project Explorer. 00300 const StringList* in_pTargetFilenameList = NULL ///< Optional: A list of the names of the destination files. Pass NULL when not specified. 00301 ) = 0; 00302 00303 /// This method is called when the user adds files to the project (Work Units or Sources), saves the project, 00304 /// or triggers any call to a Wwise operation that could alter source control files. It is called before Wwise performs 00305 /// the operation and is always followed by a call to PostCreateOrModify. 00306 /// \return The result of the operation 00307 virtual AK::Wwise::ISourceControl::OperationResult PreCreateOrModify( 00308 const StringList& in_rFilenameList, ///< A list of the names of the files that are to be added (some files may already exist) 00309 CreateOrModifyOperation in_eOperation, ///< The operation(s) that will be performed on these files 00310 bool& out_rContinue ///< A returned flag that indicates if Wwise is continuing the current operation 00311 ) = 0; 00312 00313 /// This method is called when the user adds files to the project (Work Units or Sources), saves the project, 00314 /// or triggers any call to a Wwise operation that could alter source control files. It is called after Wwise performs 00315 /// the operation and is always preceded by a call to PreCreateOrModify. 00316 /// \return The result of the operation 00317 virtual AK::Wwise::ISourceControl::OperationResult PostCreateOrModify( 00318 const StringList& in_rFilenameList, ///< A list of the names of the files that are to be added (Some files may already exist) 00319 CreateOrModifyOperation in_eOperation, ///< The operation(s) that will be performed on these files 00320 bool& out_rContinue ///< A returned flag that indicates if Wwise is continuing the current operation 00321 ) = 0; 00322 00323 /// This methods returns the list files that can be committed 00324 /// \return The result of the operation 00325 virtual AK::Wwise::ISourceControl::OperationResult GetFilesForOperation( 00326 DWORD in_dwOperationID, ///< The operation to verify on each file 00327 const StringList& in_rFilenameList, ///< The files to query 00328 StringList& out_rFilenameList, ///< Out: The files that can have the operation done 00329 FilenameToStatusMap& out_rFileStatusMap ///< Out: The file status of all files 00330 ) = 0; 00331 00332 //@} 00333 00334 /// \name Exported functions prototypes 00335 //@{ 00336 00337 /// Gets the plug-in ID list contained by the DLL file. 00338 typedef void (__stdcall* GetSourceControlIDListFuncPtr)( 00339 PluginIDList& out_rPluginIDList ///< The List of plug-in IDs 00340 ); 00341 00342 /// Gets the AK::Wwise::ISourceControl::PluginInfo class associated with a given plug-in ID. 00343 typedef void (__stdcall* GetSourceControlPluginInfoFuncPtr)( 00344 const GUID& in_rguidPluginID, ///< The ID of the plug-in 00345 PluginInfo& out_rPluginInfo ///< The returned plug-in info 00346 ); 00347 00348 /// Gets an instance of a plug-in. 00349 /// \return A pointer to an AK::Wwise::ISourceControl instance 00350 typedef ISourceControl* (__stdcall* GetSourceControlInstanceFuncPtr)( 00351 const GUID& in_guidPluginID ///< The requested plug-in ID 00352 ); 00353 }; 00354 } 00355 } 00356 00357 #endif // _AK_WWISE_ISOURCECONTROL_H
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise