|
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 DJ Studio 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\\AudioDjStudioApi.tlb" #pragma warning(pop)
using namespace AudioSoundDjStudioApi;
|
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 AudioSoundDjStudioApi.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 AudioSoundDjStudioApiF4.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\\AudioDjStudioApiF4.tlb" #pragma warning(pop)
using namespace AudioDjStudioApiF4;
|
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 DJ Studio API for .NET" API whose default is "C:\Program Files\Audio DJ Studio API for .NET\bin\release").
| • | The second step is to declare the variable that will instance the API inside the client application |
Visual C++ |
IAudioDjStudioApiObjPtr m_ptrAudioApi;
|
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(AudioDjStudioApiObj), NULL, CLSCTX_ALL, __uuidof(IAudioDjStudioApiObj), (void**)&m_ptrAudioApi);
// init the API m_ptrAudioApi->InitSoundSystem (1, 0, 0, 0, 0);
|
| • | 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 the status of a specific player: |
Visual C++ |
// manages the CallbackForPlayersEvents delegate void WINAPI CallbackForPlayersEvents (long nEvent, short nPlayer, long nData1, long nData2, float fData3, char *pBufferUnicode, long nBufferLength) { switch (nEvent) { case enumPlayerEvents_EV_SOUND_STOPPED: printf ("\rStatus: Sound stopped "); break; case enumPlayerEvents_EV_SOUND_PAUSED: printf ("\rStatus: Sound paused "); break; case enumPlayerEvents_EV_SOUND_PLAYING: printf ("\rStatus: Sound playing..."); break; default: return; } }
|
in order to allow the API to invoke these callbacks when needed, you need to call the following statement:
Visual C++ |
// init callbacks for events m_ptrAudioApi->CallbackForPlayersEventsSetPtr (UINT_PTR (CallbackForPlayersEvents));
|
please, note the usage of the "Ptr" version of the CallbackForPlayersEventsSet 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 m_ptrAudioApi->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:
