Today, I’m restarting my (well, actually I’ve seen something similar around the web) “Code Garage” concept. Basically, the idea is to post (hopefully regularly) some snippet of code that I’ve either come across, translated from some other language, or whatever and that I find myself using pretty consistently. I’ll tag them all with the “Code Garage” tag in my tag cloud.
Today, it’s a SplitQuoteComma function. VB has long had a split function, in one incarnation or another, but occassionally, you have to deal with quote/comma delimited text (i.e. text input that is comma delimited unless there’s a comma in the text, in which case the text is wrapped in quotes).
This kind of function is pretty trivial stuff, really, but I happened across a regex that makes it even trivialer (is that a word?):
PublicFunction SplitQuoteComma(ByVal Args AsString) AsString()
Dim r = New System.Text.RegularExpressions.Regex(",(?=(?:[^""]*""[^""]*"")*(?![^""]*""))")
Return r.Split(Args)
End Function
If you’ve ever had to use the Word Object Model’s Find object, you probably know it can be a bit… well… finicky. It has guids that conflict with Excel 95 typelibs which causes problems, it uses a veritable forest of optional parameters, most of which are declared as OBJECT so intellisense doesn’t work well with it, it’s a real pain to use with C# because of C#’s lack of optional parameter handling, etc, etc.
And I have a new one to add to the list.
I was recently working on a kind of super advanced mail merge facility for Word documents. Word’s MailMerge capabilities are certainly good, but they couldn’t cut the mustard for this particular batch of requirements.
However, since the MAILMERGE field (and all the various other fields in Word) have a lot of capability, I wanted to leverage that as much as possible.
Essentially, the templates to be used would embed normal mail merge fields, but Word’s Merge ability would never get used. Instead, I’d have a VB.NET assembly that would navigate through each field in the document, analyze its code, and replace it with the appropriate result. The code looks something like this:
Dim Code = Field.Code.Text
'....parse the code for the field here' determine the final field contents, put it in Content
Field.Result.Text = Content
Field.Unlink
Pretty simply stuff, really.
But, the content of the field might have embedded style information. Sort of like a stripped down HTML code system. For instance, <b> might be “Turn bold on”, and </b> would turn bold off.
First thought
Initially, I thought I could just detect the existence of the opening tag, remove all the tags, and just format the entire field consistently. It’s simple and fast. But unfortunately, some field values had tags embedded within the field, meaning that only a portion of the field’s data should be formatted.
Strike 1.
RTF??? In 2010?
Then, I figured I could just swap out the formatting code with the equivalent RTF codes, and use PasteSpecial to paste the RTF formatted data directly in the field.
While this did work, it presented a bad side effect. Since the RTF text coming off the clipboard represented specific and complete formatting information, it overrode all default formatting already applied to the field. So, say the entire document was formatted in Calibri Font. When I pasted the RTF text “{\b My Text Here}”, the end result was a field formatted in bold Times New Roman, not Calibri. So even though I hadn’t specifically set the font for the text, the paste special was assuming a default of Times.
Strike 2
That ol’ Word FIND Object
I finally realized that I was going to HAVE to use the FIND object in Word to locate those formatting marks, and then apply the applicable styles to the found text.
Performing the Find is pretty straightforward, although there’s a few things to watch for.
The first is the aforementioned Excel 95 Guid clash. What it means is that you need to access the FIND object via late binding. So obtain a FIND object from the (Field.Result range) and store it in an OBJECT variable. That will force VB.net to make latebound calls to it.
The next problem is how to actually find the marks. You’ll need to use the Find object’s wildcard support for that. The code looks something like this:
Dim Find asObject = Field.Result.Find
With Find
.ClearFormatting
If .Execute(FindText:="\<b\>*\</b\>", MatchCase:= false, MatchWildcards:= True, Forward:= True) then'the text was foundElse'The text was not foundEndIfEndWith
Again, pretty simple stuff.
But there was two problems.
The first was, the above would find the text alright, but I still needed to remove those embedded formatting marks. After a false starts, I realized that the REPLACE functionality was could do this very easily. Just mark the * (i.e. the found text that you want to keep) by enclosing it in “()”, then Replace with “\1” (the first marked substring).
Dim Find asObject = Field.Result.Find
With Find
.ClearFormatting
If .Execute(FindText:="\<b\>(*)\</b\>", MatchCase:= false, MatchWildcards:= True, Forward:= True, Replace:=wdReplace.wdReplaceAll, ReplaceWith:="\1") then'the text was foundElse'The text was not foundEndIfEndWith
The second problem was much more insidious.
It worked perfectly on fields embedded in the body of the document, but completely failed to find anything in field embedded in cells in a table. Needless to say, I was scratching my head over that one for a while.
It turns out that Find just doesn’t work right if you attempt to use it in the Result range of a Field object when that object has been embedded within a table.
The trick, then is to Unlink the field object before you attempt a find inside of it.
Dim Rng = Field.Result
Field.Unlink
Dim Find = Rng.Find
With Find
'.... continue as before
With the range no longer within the field, the Find works just like it should, regardless of whether the field is in the body of the document or embedded within a table.
So there’s my terrifically arcane Office object model trivia for the day!
So, I was working on parsing a WordPerfect Merge DAT file today…
Yep, you read that right, WordPerfect! Seriously old school stuff.
Anyway, this file format is a peculiar binary format with a bunch of binary headers surrounding all the nice juicy ASCII merge text fields. Dealing with such files in VB6 was easy, but it seems that the few times I’ve had to work with this type of thing in .NET, I always end up stubbing my toe on encoding.
You see, all strings in .NET are UNICODE, and reading binary data like this into a string involves an encoding or decoding process. In order for things to work the way you’d (or at least, I’d) expect them to, you have to be SURE that the strings will round trip properly. And boy, they weren’t for me.
I wrestled with it all day, finally knocking off to go home and unwind.
But it was still bugging me.
So I whipped up this little sample (why didn’t I think of this at noon today<sigh>).
PrivateSub TestEncode()
Dim b(255) AsByteFor x = 0 To 255 : b(x) = x : NextDim buf AsString = System.Text.Encoding.Unicode.GetString(b)
Dim c(255) AsByte
c = System.Text.Encoding.Unicode.GetBytes(buf)
For x = 0 To 255
If c(x) <> x ThenStopNextStopEndSub
If the code stops at that stop in the last FOR loop, something didn’t round trip properly and you’re pretty much guaranteed a headache.
And sure enough, the UNICODE encoding object failed to round trip. But so does the ASCIIENCODING, UTF8, etc etc.
On a whim, I tried the “default” object, SYSTEM.TEXT.ENCODING.DEFAULT.
And it worked!
A quick check revealed that on my system, DEFAULT is actually the encoding object for the codepage 1252, which is the Windows ANSI ASCII encoding. Read more about it here. But 1252 is the codepage you want to use if you want EVERY SINGLE binary value from 0-255 to map to the exact same unicode character when you read the file into a string.
Long story short, if you’re used to looking at binary files via a hex editor, and you want to manipulate those files in VB, you have two choices.
Read the file into a BYTE() array as raw data, then operate on the bytes directly.
Read the data into a string, but be SURE to use the proper encoder, like so:
Dim Buf asString= My.Computer.FileSystem.ReadAllText(MyFileName, System.Text.Encoding.GetEncoding(1252))
Option 1 is great if you need to work on the data as, more or less, strictly byte type info. But it’s a real pain if much of the data is string type stuff.
Option 2 is MUCH easier to work with for mostly string data (you can use INSTR, MID, LEFT, RIGHT, cutting and chopping much more easily than with byte arrays), BUT you have to have read the data in via the right encoder or it will be “altered” during the loading process and won’t contain the same bytes that were actually in the source file.
Doing this won’t work:
Dim Buf asString= My.Computer.FileSystem.ReadAllText(MyFileName)
Because the ReadAllText routine uses, as its default, the UTF8 encoder.
Hopefully, putting all this down in writing now will keep me from forgetting about it the next time I’m mucking with funky file formats!
A while back, I wrote up a short post about calling C function pointer style interfaces with VB.net. When I started into that, what I was really wanting was a pure VB.net solution for calling the amBX API interfaces. There was already a library out to do the job, but that would have required including a separate dll, and, well, it’s not VB! It was C++ and C#.
But what’s amBX? Well, the basic system looks like this:
That box in the middle is actually called a “wall washer.” It contains several banks of lights that shine up onto the wall behind the unit. The speaking looking things are exactly that: LED lights that look similar to speakers.
You can also get an extension pack:
which consists of 2 fans, and a rumble bar (basically just a bar with two vibration motors in it).
In action, it looks like this:
Anyway, flash forward to now and my VB version of that library is ready for an initial release.
I call it amBXLibrary (catchy eh?)<g>.
amBXLibrary
The whole thing is in one ambx.vb source code file, and there’s no external references necessary, so, literally all you do is drop that source file into your project and you’ve got support for the amBX device set. Yes, it could have been broken up into a separate file for each class, and, normally, that’s how I approach things. But in this case, knowing I was planning on making this code publicly available like this, I opted for the simplest distribution form possible. If you must have it split up, feel free!
One more important note: You will need to have the ambxrt.dll file somewhere accessible, either in the same folder as your application or on the path. This file is installed with the amBX system, but won’t normally be on the path.
General Usage
All the internal classes are part of the amBXLibrary namespace. You’ll need to add an imports for that or set it in the project properties (or remove the Namespace line from the source) before you can use it.
The root class is amBX. To start up amBX and connect to its drivers, you’ll need to call the Connect method:
amBX.Connect(1, 0, "My Application", "1.0.0")
The first 1 and 0 are the required major and minor version of the amBX library. Since there’s only a version 1.0, that’s the only possible value to those arguments at this point. The next args are the string name of your application and a string version of the version number of your application. As far as I can tell, these values can be anything you want.
When you’re finished with amBX, be sure to call the Disconnect method (although this is not strictly necessary).
amBX.Disconnect()
The amBX class is a static class, which means you can’t instantiate instances of it. All its methods are Shared. It exposes several collections, into which you can add new amBX objects. Those include:
amBX.Lights
amBX.Fans
amBX.Rumbles
amBX.Events
amBX.Movies
Create a new amBX light like this:
Dim LeftLight = amBX.Lights.Add("Left", amBXLibrary.Locations.East, amBXLibrary.Heights.AnyHeight)
Technically speaking, since the newly created light is automatically added to the Lights collection, you don’t absolutely need to keep a local reference to it. But doing so makes it easier to work with your objects. Further, generally speaking, in amBX applications, you create the objects you need up front, when your application loads, and you use them until the application quits, so it tends to be more convenient to keep local references.
The first argument, the name, is simply an arbitrary descriptor of the object you’re creating. That is not part of the underlying amBX library. I added it more for convenience than anything. That said, you don’t have to give names to your objects. You can also create a light like this:
Dim RightLight = New amBX.Light(amBXLibrary.Locations.West, amBXLibrary.Heights.AnyHeight)
Notice, no name, and I just created the object directly with New. Note however that the new Light object is still added to the Lights collection and you can still reference it my index or via an enumeration.
Threading
amBX has several different options for multi-threading. This library only uses one. When you initially Connect, a background thread is started internally which calls the amBX.Update method 20 times per second. You can alter the timing however you want, and even turn it off by settings UpdatesPerSecond to 0. If you do turn it off, you’ll be responsible for calling the amBX.Update method periodically yourself.
Changing Objects
All the amBX objects are fairly simple. The lights have a Color; the fans, an Intensity; and the rumbles, an Intensity, Waveform, and speed. You simply set the properties however you want. The next time the amBX.Update method is called, the changes will be sent to the amBX drivers and the hardware updated.
Events and Movies
Event and Movie objects operate a little differently from the other amBX objects. Events are usually for short event sequences that can’t be stopped or paused. Movies are for longer sequences where you may want to stop or pause the sequence arbitrarily.
With Events, you generally create them during your application Load process and then simply call the Play method anytime you need the event sequence to play out.
Since Movies tend to be much longer sequences, you’ll generally create them right before you need to play them, Play the movie, and then dispose of the object.
Disposing of Objects
All of the effects objects in the library implement the IDisposable interface, so it’s usually best to explicitly Dispose the object once you’re done with it. Usually, this is easiest to do by using a Using Block:
Using Evt = New amBX.Event("c:\SomeEffectFile.ambx_bn")
Evt.Play()
End Using
Enabling and Disabling
You’ll notice that several of the Enable/Enabled/Disable members are seemingly arbitraryly properties or methods. For instance, Light.Enabled is a boolean property, whereas Fan.Enable is a method, and fan.Enabled is a readonly property. This is because the different objects deal with enabling in different ways. This is the nature of the amBX drivers, not an arbitrary decision of mine!
In the case of a fan, the Enabled property will return which state the can is currently in, which can include Enabled, Disabled, Enabling or Disabling. However, in the case of a Light, the light can only be Enabled or Disabled.
Also note that although the amBX documentation indicates that disabling an object will “cause it to retract itself from the user experience”, I’ve found that doesn’t appear to be the case. When I Disable objects, it simply means that they no longer react to any property changes to the them.
For instance, if you set a fan intensity to .5, then disable the fan, it continues to spin. But, setting the intensity to 0 will no longer alter the fan speed. You must Enable the fan again in order to change its intensity again.
Rumble objects are particularly troublesome in this respect, since there doesn’t appear to be a way to turn one off once it’s turned on. I’ve found that releasing the object and then recreating it will turn the rumbler off, but that causes more problems. So, as currently implemented, you MAY have problems with rumble effects (at least, problems getting them to stop!).
From what I’ve seen online, this is described as a known bug in the amBX drivers, but I’m not completely sure.
The Tricky Parts
I’ve really already covered (in the post referenced at this top of this post) what was the most difficult aspect of getting this library operational. All of the amBX interfaces are C style function pointer structures. These are easy to deal with in C, but more difficult to work with in VB.net. However, pleasantly, they are, in fact completely interoperable with VB.net (or C# for that matter). You just have to use the right combination of IntPtr, and Marshalling to convert those C function pointers to .net Delegates that canbe called from managed code with no problems at all.
If you want to know more, check out my previous post here, and pay special attention to the Generate methods in the source code. For instance, here’s the one for the Event object:
It uses the GetDelegateForFunctionPointer method of the Marshal class to create the necessary delegate from the function pointers passed back by amBX. Then, it’s just a matter of retrieving those function pointers correctly, managing the whole mess efficiently and calling the delegates when you need them.
The Caveats
This is a very “in flux” library at this point. In reality, I don’t even have any amBX hardware to test on. Everything I’ve done so far has been using the Virtual amBX Test Device, a program that simulates all the various amBX hardware that’s out there at this point.
I’ve implemented all the various methods and properties of the C amBX interfaces, but I have not tested them all out at this point (specifically, the RunThread and StopThread methods of the amBX object).
I also have noticed the above mentioned problem with disabling rumble devices (it just doesn’t seem to work right), and the only workaround seems to completely kill the rumbler, such that you can’t turn it back on at all without disconnecting from amBX and reconnecting.
However, I’ve noticed similar issues when working with the “amBX Test Tool” that comes with the amBX SDK, so I’m not completely sure whether it’s something in my code, or with the drivers themselves.
That said, the lights, fans, events, and movies all seem to work spot on, and I’m not much concerned about the rumble effects myself anyway<g>.
My Intentions…
I’ve got some very specific things I intend to use amBX for, but mainly, once I find a set for a reasonable price, I’ll be disassembling it and mounting the various pieces in a purpose built cabinet. My hope is to use all the elements (lights, fans and rumblers) but I’m not completely sure that’ll make sense.
I’m also working on a general purpose “screen color tracker” that will drive the amBX lights based on whatever happens to be onscreen, not use amBX enabled DirectX windows. But that’s a whole other project in and of itself!
The Code
I’ve made this project Open Source via CodePlex. Check out the project page at ambx.codeplex.com.
Alternately, you can download the test project (with the ambx.vb library source) here.
And Finally…
Let me know what you think! Have suggestions? Ways to improve the library? Things you would have done differently? Fixes?
By all means let me know. I’ll do what I can to get improvements and suggestions implemented.
I’ve been playing recently with the amBX ambient effects library and devices.
Essentially, it’s an effects platform that allows you to easily create light, wind and rumble effects to coordinate with what’s going on on-screen, in a game, in media players, or what-have-you. The lighting effects are nothing short of fantastic. The rumble and fan effects…. meh. They’re interesting, but I’m not sure where that’ll go.
Regardless, the API for amBX is all C style objects, which means essentially an array of function pointers to the methods of the object; not really an API that VB.net likes to consume. Be sure to grab the amBX developer kit here. You’ll also need to core amBX software available from the main website. Finally, play around with the “Virtual amBX Test Tool”. It’ll allow you to experiment with all the amBX features and functions without having to buy anything at all. Of course, eventually you’ll want to get at least the starter kit, with the lights. But it’s not necessary to begin experimenting.
Hats off to Philips for making this possible!
Here’s an example of the structure definition from the amBX.h header file that comes with the API (I’ve clipped out comments and other bits):
As you can see, each element in the structure is made up of a pointer to a function. The various functions all take, as their first argument, a pointer back to this structure. Under the covers, this is how virtually all object oriented languages function, it’s just the the compiler usually hides all this nasty plumbing so you don’t have to deal with it regularly.
But this presents a problem. VB.net is “managed” code, and as such, it likes things to be wrapped up in nice “managed” bits. There are plenty of good reasons for this, but these function pointers are decidedly not nice and tidy managed bits! So, what to do?
One solution is the approach Robert Grazz took here. It’s a solid solution, no doubt, and I learned a lot from looking at his approach, but, this being VBFengShui, I wanted that same functionality in native VB.net with no additional dll files hanging around!
Delegates to the Rescue!
A delegate in .net is essentially a managed function pointer. In VB.net, they’re most commonly used to handle events, but you wouldn’t really know it, because VB’s compiler does a good job of hiding all that plumbing from you. However, unlike VB6 and earlier, in VB.net, all the plumbing can, if you’re willing, be “brought into the daylight” and used however you want.
There are many, many discussions about delegates for VB.net out on the web. A really good Introduction to the concepts by Malli_S is on codeproject, so I won’t rehash the basics here.
The problem is, delegates in VB.net tend to be generated by using the AddressOf operator, and I already had the function addresses (they’re in that C structure). I just needed to get a delegate that would allow me to call it.
Some Googling turned up several good posts that provided pointers, including this one on StackOverflow. But it wasn’t exactly all the steps necessary.
Getting the C Structure
The first step toward getting something working with amBX is to retrieve the main amBX object. You do this through a standard Windows DLL call.
<DllImport("ambxrt.dll", ExactSpelling:=True, CharSet:=CharSet.Auto)> _
PublicSharedFunction amBXCreateInterface(ByRef IamBXPtr As IntPtr, ByVal Major As UInt32, ByVal Minor As UInt32, ByVal AppName AsString, ByVal AppVer AsString, ByVal Memptr AsInteger, ByVal UsingThreads AsBoolean) AsIntegerEnd Function
Assuming you have the ambxrt.dll file somewhere on your path or in the current dir, the call will succeed, but what exactly does that mean?
Essentially, you pass in the Major and minor version numbers of the Version of amBX you need, and two strings indicating the name of your app and the version of your app. No problems with any of that. But that &EngineHandle is the trick.
It means that this call will return a 4 byte pointer to a block of memory that contains the amBX object structure, which is, itself, an array of 4 byte function pointers to the various methods of the amBX object. Therefore, in VB.net, that argument is declared ByRef IamBXPtr as IntPtr.
Now, we need a place to store that “structure of pointers.” Going through the ambx.h file, I ended up with a structure that looks like this:
<StructLayout(LayoutKind.Sequential)> _
PrivateStructure IamBX
Public ReleasePtr As IntPtr
Public CreateLightPtr As IntPtr
Public CreateFanPtr As IntPtr
Public CreateRumblePtr As IntPtr
Public CreateMoviePtr As IntPtr
Public CreateEventPtr As IntPtr
Public SetAllEnabledPtr As IntPtr
Public UpdatePtr As IntPtr
Public GetVersionInfoPtr As IntPtr
Public RunThreadPtr As IntPtr
Public StopThreadPtr As IntPtr
EndStructure
That StructLayout attribute is particularly important. It tells the compiler that the structure should be layed out in memory JUST AS it’s declared in source code. Otherwise, the compiler could possibly rearrange elements on us. With Managed Code, that’d be no problem, but when working with unmanaged C functions, that would not be a good thing!
And finally, we need a way to retrieve that function pointer array and move it into the structure above, so that it’s easier to work with from VB.net. That’s where the System.Runtime.InteropServices.Marshal.PtrToStructure function comes in. This routine will copy a block of unmanaged memory directly into a managed structure.
Private _IamBX As IamBX
Private _IamBXPtr As IntPtr
...
amBXCreateInterface(_IamBXPtr, 1, 0, “MyAppName”, “1.0”, 0, False)
_IamBX = Marshal.PtrToStructure(_IamBXPtr, GetType(IamBX))
And presto, you should now have the _IamBX structure filled in with the function pointers of all the methods of this C “Object”.
Calling the C Function Pointer
At this point, we’ve got everything necessary to call the function pointer. Take the CreateLight function. The C prototype for this function is shown at the top of this page. As arguments, it takes a pointer back to the amBX structure, 2 32bit integers describing the location and height of the light source, and it returns are pointer to another structure, in this case, an amBX_Light structure, which contains another set of function pointers, just like the amBX structure described above.
First, we need to declare a delegate that matches the calling signature of the CreateLight C function we’ll be calling:
<UnmanagedFunctionPointer(CallingConvention.Cdecl)> _
PrivateDelegateFunction CreateLightDelegate(
ByVal IamBXPtr As IntPtr, _
ByVal Location As Locations, _
ByVal Height As Heights, _
ByRef IamBXLightPtr As IntPtr) As amBX_RESULT
The key points here are:
Make sure you have the CallingConvention attribute set right. Most C libraries will be CDECL, but some libraries are STDCALL.
Make sure your parameter types match, especially in their sizes. Not doing this will lead to corrupted called or system crashes.
Now, create a variable for the delegate and use the Marshal.GetDelegateFromFunctionPointer function to create a new instance of the delegate, based on the applicable function pointer. Since the function pointer for the CreateLight function is stored in the CreateLightPtr field of the _IamBX structure, we pass that in as the pointer argument.
IMPORTANT NOTE: There are 2 overloads for the Marshal.GetDelegateFromFunctionPointer function. Be sure to use the one what requires a second argument of the TYPE of the delegate to create. Using the other one will fail at runtime because it won’t be able to dynamically determine the type of delegate to create.
Next, call the function via the delegate, just as if it was a function itself.
Finally, use Marshal.PtrToStructure again to copy the array of function pointers returned into another structure, this one formatted to contain the function pointers of the Light object that just got created.
Dim d As CreateLightDelegate = Marshal.GetDelegateForFunctionPointer(_IamBX.CreateLightPtr, GetType(CreateLightDelegate))
Dim r = d(_IamBXPtr, Location, Height, _IamBXLightPtr)
_IamBXLight = Marshal.PtrToStructure(_IamBXLightPtr, GetType(IamBX_Light))
The amBX library is much, much larger than just this little bit I’ve shown here. Once I get the entire thing coded up, I’ll be presenting it here as well.
But in the meantime, if you have a need to interface with C style function pointer objects, don’t let anyone tell you it can’t be done in VB.net
Final Note
As you may or may not have guessed, amBX is a 32bit library and its interfaces, functions and arguments all live in 32bit land. If you’re working with VS2008, BE SURE to set your project to the x86 platform, and NOT “Any CPU” or “x64”! The default, for whatever reason is “Any CPU”, which means things will work properly when run under 32bit windows, but things won’t work well at all if run under a 64bit OS.
