Binary messages

[size:17pt]Binary messages[/size]

Since they're something I'm often being asked about, and something not many people seem to understand, in this article I'm going to explain how binary messages work in Lacewing. (sorry about the weird formatting, something bad happened to the spaces when transferring it to the forum...)

[size:14pt]Why should I use binary messages?[/size]

I guess if you're reading this article, you're probably currently doing things the Moo way and sending delimited strings to be parsed on the receiving end with String Parser.

Let's imagine we have a networked application that has to send two numbers (perhaps X and Y coordinates?) - it sends them like this:

104,178

That string is 7 characters in length, which means Lacewing will use (excluding headers) seven bytes of bandwidth to transmit it. If we were using binary messages instead, this could be sent in only TWO bytes (or four if the numbers were larger than 255).

How? Well, each character in a string (letter, string, or number) is represented by an ASCII number (search for an "ASCII table" to see which numbers are used for different characters). The character that represents the number "1" is character number 49, the number "0" is character number 48. To send a string, Lacewing uses 1 byte (a byte can be any number from 0 to 255) per character. So the string above would be sent like this:

Please login to see this picture.

Which means the seven bytes:

Please login to see this picture.

are transmitted over the network. This is obviously a complete waste of bandwidth, because all we want to send is two numbers (104 and 178). Lacewing, thankfully, allows you to send the numbers directly, instead of sending a string, and that's what the binary message feature does.

That means you can send these bytes instead:

Please login to see this picture.

And read them on the other end. Considering how frequently you're likely to be sending messages, this can save a lot of bandwidth.

[size:14pt]How do I use binary messages?[/size]

I'll show an example of how to send the two numbers we were talking about above, and read them on the other end.

[size:11pt]Sending the binary message[/size]

Old code

Lacewing : Send text Str$(104) + "," + Str$(178) to channel on subchannel 0

New code

Lacewing : Push byte 104
Lacewing : Push byte 178
Lacewing : Send binary to channel on subchannel 0

[size:11pt]Receiving the binary message[/size]

Old code

+ On text channel message on subchannel 0
- String Parser : Set source string to Received$("Lacewing")
- Active : Set X position to Val(listGetAt$("String Parser", 0))
- Active : Set Y position to Val(listGetAt$("String Parser", 1))

New code

+ On binary channel master on subchannel 0
- Active : Set X position to Byte("Lacewing", 0)
- Active : Set Y position to Byte("Lacewing", 1)

And that's about it, as far as sending and receiving a message composed of bytes goes. Here's the catch: A byte can only hold a value from 0 to 255 (when you use the expression to read it as unsigned) or from -128 to 127 (when you use the expression to read it as signed). If you want values beyond this range, you'll have to use one of the other data types.

Lacewing allows you to write and read the following types from binary messages:

Please login to see this picture.

It's quite easy to understand how to use all of these types in your binary messages, providing you understand how Lacewing builds binary messages. When you add something to the binary to send:

Please login to see this picture.

You could now send the binary, and then on the receiving end, read the respective type at the respective index. So if you read an integer at 3, you'd get 31333337. If you read a byte at 7, you'd get 100. Basically, the position of everything in the binary starts at 0 (the first thing you add will always be at index 0) and from there, the index depends on how big the things you added afterwards were.

If we sent the binary above, containing the numbers 3, 572, 31333337 and 100, it would be 7 bytes in size. If you sent this as a delimited string "3,572,31333337,100", it would be 18 bytes total. This should give you an impression of how much space you can save using the binary messages with Lacewing.

I hope if binary messages previously made no sense to you, they make a little more now. Good luck

They take up the length of the string in bytes. You probably want to push a short with the length beforehand or something.

To avoid trouble, you could push the string at the end of the stack, so you can just subtract the size of the things before it from the total stack size to work out the string length.

Quote from Fanotherpg

Jamie to be honest with you IF you will make the whole help file for Lacewing as general and as informative as this one you will steal our souls.

It's the best freaking article about networking aspects of MMF which I saw from year 2000. Congratulations mate and hopefully you will finish the job.

Aw, thanks

Quote from variant

Hi,

Can anyone please post an example of sending a string with a stack, I get how to send the numbers, but the strings are confusing me.

-Thanks, Variant

If you ONLY want to send a string, you should use "Send text", not the stack messages.

But let's say you want to send an integer followed by a string:

As I said in the article, the easiest way to send a string in a stack is to leave the string to the end of the stack. So:

Push integer 420
Push string "Hello"

Then you could, on the receiving end, use Integer("Lacewing", 0) to read the number 420, and String("Lacewing", 4, StackSize("Lacewing") - 4) for the string.

We read it from the offset 4 because an integer is 4 bytes in size, and we just had one integer before the string. We also subtract 4 from the size of the stack for the length of the string for the same reason.

Please login to see this link.

Please login to see this link.