|
Adding the API to an unmanaged Visual C++ project |
  
|
|
Adding the API to an unmanaged Visual C++ project |
|
The .NET runtime allows unmanaged COM aware clients to seamlessly access .NET Components through the "COM Interoperability" and through the tools provided by the framework. This ensures that COM aware clients can talk to .NET components, as if they were talking to classic COM Components: "Audio Sound Editor API for .NET" API allows this interoperability with unmanaged Visual C++ through a certain number of steps.
| • | The first step is to import the type library of the API, which contains all of the needed information for allowing the COM client to talk with the API, by adding the following statements at the beginning of your code: |
Visual C++ |
#pragma warning(push) #pragma warning(disable:4146) #pragma warning(disable:4786) #pragma warning(disable:4278) #import "mscorlib.tlb" #import "..\\..\\..\\bin\release\\AudioSoundEditorApi.tlb" #pragma warning(pop)
using namespace AudioSoundEditorApi;
|
when using MFC (Microsoft Foundation Classes) a good place to add this code is usually the "stdadx.h" header file. It must be remarked that this specific code will make use of the AudioSoundEditorApi.dll assembly which is compiled against version 2.0 of the .NET framework: this means that the target machine will need the presence of version 3.5 of the .NET framework in order to allow the container application to run; in case it shouldn't be available, the Windows system will raise a message allowing the possibility to proceed with the related installation.
In case you should prefer relying upon the AudioSoundEditorApiF4.dll assembly, which is compiled against version 4 of the .NET framework, allowing to run on Windows systems where version 3.5 of the .NET framework is not installed by default (as seen for Windows 8 and 10) the code to use would be very similar:
Visual C++ |
#pragma warning(push) #pragma warning(disable:4146) #pragma warning(disable:4786) #pragma warning(disable:4278) #import "mscorlib.tlb" #import "..\\..\\..\\bin\release\\AudioSoundEditorApiF4.tlb" #pragma warning(pop)
using namespace AudioSoundEditorApiF4;
|
Please, note that the usage of the relative path for the ".tlb" file is in this case related to the path of the samples installed by our setup package: in your case you could eventually enter the absolute pathname that may vary depending upon the installation folder of the "Audio Sound Editor API for .NET" API whose default is "C:\Program Files\Audio Sound Editor API for .NET\bin\release").
| • | The second step is to declare the variable that will instance the API inside the client application |
Visual C++ |
IAudioSoundEditorApiObjPtr g_ptrAudioEditorApi;
|
where IAudioDjStudioApiObjPtr is the COM interface used to drive the API.
| • | The third step is to initialize the COM subsystem, create an instance of the API inside the code and, finally, initialize the API |
Visual C++ |
// initialize COM CoInitialize (NULL);
// create an instance of the API and obtain its pointer CoCreateInstance(__uuidof(AudioSoundEditorApiObj), NULL, CLSCTX_ALL, __uuidof(IAudioSoundEditorApiObj), (void**)&g_ptrAudioEditorApi);
// init the API int result = g_ptrAudioEditorApi->InitEditor ();
|
| • | The next optional step is to set the callbacks that allow the client application to be informed about events occurring inside the API. For example we could need to be informed about percentage of advancement of loading, exporting and editing operations: |
Visual C++ |
// manages the CallbackPercentage delegate void FAR PASCAL PercentageCallback (enumOperationsWithPercentage nOperation, short nPercentage) { switch (nOperation) { case enumOperationsWithPercentage_OPERATION_SOUND_LOADING: printf ("\rLoading percentage %d%%", nPercentage); break; case enumOperationsWithPercentage_OPERATION_SOUND_EXPORT: printf ("\rExporting percentage %d%%", nPercentage); break; } }
// manages the CallbackEditPerc delegate void FAR PASCAL PercentageEditCallback (short nPercentage, enumSoundEditCommands nCommand) { printf ("\rEditing percentage %d%%", nPercentage); }
|
in order to allow the API to invoke these callbacks when needed, you need to call the following statements:
Visual C++ |
// init callbacks for events g_ptrAudioEditorApi->CallbackPercentageSetPtr (UINT_PTR (PercentageCallback)); g_ptrAudioEditorApi->CallbackEditPercSetPtr (UINT_PTR (PercentageEditCallback));
|
please, note the usage of the "Ptr" version of the CallbackPercentageSet and CallbackEditPercSet methods: the "Ptr" version of these methods allows passing the address of the callback function as a pointer because the COM client is totally unaware about .NET delegates.
At this point you could add all of the needed code in order to allow the API loading and editing audio files: see the How to use the API in your projects tutorial for related guidelines.
| • | The final step, immediately before exiting the client application, is to dispose the API and un-initialize the COM subsystem |
Visual C++ |
// dispose the API and all of the allocated resources g_ptrAudioEditorApi->Dispose ();
// uninitialize COM CoUninitialize ();
|
Note about the usage of Unicode
Due to the fact that all of the strings passed/returned to/from the API are in Unicode, when dealing with Visual C++ projects it's strongly recommended to set Unicode as character set inside the project's properties as seen on the image below:
