Call library with struct as parameter - several problems

Question

Hi everyone,
I'm trying to send a MIDI sysex message to a midi device through winmm.dll using MidiOutLongMsg. I have trouble figuring out how to pass the parameters right.
I need to call three functions (midiOutPrepareHeader, midiOutLongMsg, midiOutUnprepareHeader), all of them having the same form
MMRESULT midiOutPrepareHeader(
HMIDIOUT hmo,
LPMIDIHDR lpMidiOutHdr,
UINT cbMidiOutHdr
where HMIDIOUT hmo is a handle that I have already. Troubling me are the other two parameters. cbMidiOutHdr is the size (in bytes) of the struct lpMidiOutHdr. This is a struct of the form
typedef struct {
LPSTR lpData;
DWORD dwBufferLength;
DWORD dwBytesRecorded;
DWORD_PTR dwUser;
DWORD dwFlags;
struct midihdr_tag far * lpNext;
DWORD_PTR reserved;
DWORD dwOffset;
DWORD_PTR dwReserved[4];
} MIDIHDR;
(Struct: http://msdn2.microsoft.com/en-us/library/ms711592.aspx
PrepareHeader http://msdn2.microsoft.com/en-us/library/ms711634.aspx
SendMessage http://msdn2.microsoft.com/en-us/library/ms711629.aspx
UnprepareHeader http://msdn2.microsoft.com/en-us/library/ms711641.aspx)
[Note: The full code for what I want to do can be found here http://www.borg.com/~jglatt/tech/lowmidi.htm (section "outputting system exclusive MIDI messages) - basically I need a translation of this code to LabView.]
The following are my problems:
a) How do I emulate a struct in LabView? (other threads suggest that this is done by clusters)
b) How do I pass a pointer to a struct (cluster?) to a DLL?
c) If I can use a cluster for this struct, how do I represent the LPSTR lpData in the cluster, i.e., a pointer to my data?
d) how do I get the struct size for cbMidiOutHdr?
This is how far I got, lots of it with the help of several threads in this forum:
a) use a LabView cluster
b) use "adapt to type" in the dll call (couldn't get this to work)
c) I use a type cast on my string in the hope that what it returns is the register address (and I'm probably superwrong here)
d) my cluster consists of 9 elements of 4 byte datatypes, so I just use 36 for cbMidiOutHdr
The dll seems to be happy with the way I pass the cluster - I get error codes of 0 in both the PrepareHeader and UnprepareHeader functions. However, sending doesn't work (error code 7). Guessing that the type cast returns a pointer, I have also cast the cluster to an Int32 and passed that parameter as pointer to numeric value. Interestingly, the PrepareHeader and UnprepareHeader functions are still happy, but I get a different error code from the sending (code 11)
Most of what I've done so far is guesswork, and I'm out of guesses now. I've attached the code to this post (it uses VIs from the NI MIDI example library ftp://ftp.ni.com/pub/devzone/epd/midi-example.llb ). I'd appreciate any help with this. Thanks!
Attachments:
Write MIDI SysEx Message.vi ‏21 KB

Answer 1

First off, this problem doesn't have anything to do with control references; those have meaning only inside of the LabView environment.
My first suggestion is to look for a higher-level library that will do whatever MIDI function you are trying to call. If you can find an ActiveX or .NET object that will control the MIDI subsystem, I recommend that you use it instead since it will be a lot easier.
If calling the DLL directly is the best option (and calling DLLs is absolutely the way to go when you need high performance) then you need to understand how LabView passes data to library functions. That is described here:
http://zone.ni.com/reference/en-XX/help/371361D-01/lvexcodeconcepts/configuring_the_clf_node/
As you can see there are a lot of ways to pass data, but they boil down to this: LabView can pass, via various levels of dereferencing, a pointer to some [mostly] flat data. Things are easiest when your DLL mimics LabView's own data storage methods. For example, wiring a cluster into a node set with Adapt to Type passes a handle (struct**, pointer to pointer to [mostly] flat data). So if you are writing your own DLL, it's pretty easy to write something that works nicely with LabView data (e.g., strings with 4-byte length headers, self-describing arrays) and in fact the result is cleaner looking than its "pure C" variant because of the self-describing arrays and string length prefixes. (I say "mostly" flat because LabView clusters with variable-length elements aren't stored in a flat format.)
When it comes to matching someone else's API things get harder, and in this case you are out of luck; you are going to have to write a LabView-callable wrapper function in C because LabView can't mimic the exact data structure needed. The problem is not the struct; there is a sneaky way to pass a pointer (vs a handle) to a struct, which is to do this:
Generate a cluster in LabView representing the struct (atomic numeric data only! no strings arrays etc!)
Flatten to string using native byte order.
Convert string to byte array.
Configure the call library function note to accept a pointer to an unsigned byte array. (NOT a C-string as suggested at the bottom of the page in the link above; your data may have internal 0x00s, and it certainly doesn't need an extra 0x00 at the end!)
The reason this works is that a pointer is just an address; as long as all the right bytes are in memory in the right order starting at that address, all is well. The DLL doesn't know that LabView thinks it is passing a pointer to an array of bytes, it just gets the pointer to the first byte and it reads and interprets those bytes according to its own struct def. Reverse the process cooming back from the DLL (convert byte array to string, unflatten from string against the LV cluster.) This method will work for any flat struct.
In LabView 8.5 there may be a less bogus way of doing this, which is to pass the cluster in with Adapt to Type and select "Array Data Pointer" as the format. This is new and I haven't tried it.
But in your case, you want to point to a struct that contains a pointer to a string plus some numeric data and another pointer, and this you can't do directly. LabView does not expose the location of a string to you anywhere outside the Call Library Function node, so there's no way to "find the pointer" to a LabView string from outside the DLL. What you need to do in this case is write a wrapper function in C that takes your LabView data. Only then will LabView "tell you where the bytes are" and promise not to fiddle with them until the library call is complete. Once you are in C-land, you can throw pointers around to your heart's content. As long as you do it all perfectly, all will be well. (If you write one byte too many on output, boom! :-)
There are a few ways to do this. You could make a cluster that has meaning in LabView, e.g. replace lpData with a LabView string, then pass the cluster in to your wrapper function set to "Adapt to Type"; that will pass a handle to the cluster. You can generate the .c file from the Call Lib Fuction, and it will outline where the data is.
Complications: In this case it's your job to convert the handle to the labview string (which has 4 bytes of length as a prefix and no trailing 0x00) to a C-string by malloc()'ing a new buffer and memcopying the string out. There might be something in the LV CIN tools that does this, I'm not sure. Make sure you release the new string after the MIDI call.
The lazy route (which is what I would do) is pass the string as the first arg and all of the numeric stuff as the second arg, leaving the space for lpData as you have now. (I don't know what struct "midihdr_tag" is, but if that's not something you were passed in a previous call, you'll need to add a third argument for that cluster and treat it similarly.) Then you can tell LabView that it should pass the string arg as a C-string pointer. Inside your wrapper, extract the pointers and stuff them into the data structure as needed. Dereference once (to go from handle to pointer) and make the MIDI call. To be clean, put everything back where it was before in the cluster; in particular don't believe you can pass out lpData* and do whatever you want with it in LabView; LabView will release/change that address as soon as you leave the output string unwired or do anything to it (e.g. concatenate.) You'll be creating a new string buffer and a new pointer on your next MIDI call.
All of this complication is a result of a) LabView's hiding the details of memory allocation/deallocation from you and b) LabView's internal data structures being a bit different from C conventions (e.g. LabView strings vs. C strings). The second means that even when LabView is using non-flat data structures (e.g. cluster containing an array), you can't just blindly pass them along to a C function and expect it to work right. It would be nice if NI would write a little mini-compiler into the Call Library Function that would do what our wrapper function is going to do, but that's probably a fairly significant project. 
Still, each function wrapper is only going to have about 10 lines of C. You can put wrappers for all the MIDI functions you want to call into a single DLL, then ship that DLL with your app.
(Now you see why I suggested you look for an ActiveX MIDI control!)
-Rob Calhoun