Table of Contents

include/AK/Wwise/SourceControl/ISourceControl.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 /// 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