Decal Development Forums

[Saitoh_TD]

Howto: Protocol, EchoFilter, Visual Basic and You

Definitions:

Mask - A was of combining flags into one variable. Usually it involvers combining a variety of booleans into one Double
Hex - Hexadecimal, a base 16 numbering system
Long - Long Integer, no decimal place allowed
Double - Known as a Double Word to C people, It is 8 Bytes of data.
Wrapper- A program or bit of code that sits between your program and another program to translate and simplify communication between the two
Filter - A Wrapper for AC -> Decal Protocol

Concepts:

Useing the Network Protocol commning into Decal is a fundamental of programming a plugin. It is everything that your character is, sees, hears, and does. The Echofilter doesn't have states. You have to deal with each packet as it comes in and record what you want remembered yourself. Or, you can use a filter. A filter is just a "wrapper" of the EchoSink. It finds things that are important and holds that information for you so that you don't have to duplicate creating the same container all the time.

Still, there may be time that you are looking for something that you can't get from a filter. Or, if you don't want to rely on a filter, you will want to snag information from the EchoFilter yourself.

The EchoFilter itself is a Filter, it takes the raw data comming in from the Internet and applies the formatting from the Messages.XML file to that message. This saves us a tremendous amount of work. Still, there is a little bit of work that we need to do. There are things like Masks and Flags, Vectors, amd sub-Id's to deal with.

Let's begin.

Header:

Gotten use to making controls yet?

Code:

Private WithEvents NetEcho As DecalFilters.EchoFilter



Initialize:

And set it up, just like every other filter...

Code:

Set NetEcho = pSite.NetworkFilter("DecalFilters.EchoFilter")



Usage:

Now, we wait... wait for those sneaky packets to make a rush at the client. Remeber Callbacks from previous Howto's? Since we defined NetEcho with a WithEvents, when our EchoFilter receives a packet, it will tell our plugin that there is a message waiting for us. So, we need to make a subroutine to catch it.

Code:

Private Sub NetEcho_EchoMessage(ByVal pMsg As IMessage)
On Error GoTo NetEcho_EchoMessage
' Occurs when an AC packet is recieved

'Put code here

Exit Sub
NetEcho_EchoMessage:
PluginSite.WriteToChatWindow "You messed up - " & Err.description
End Sub



Any time a packet arrives, EchoMessage is called with an IMessage. IMessage is a pre-chewed message, meaning already parsed using the messages.XML.

The On Error is there because playing with packets is super-easy to mess up and having it spit out the reason it's dying will save you a lot of headaches.

What shall we look for first? I know. Lets grab the character's name as they log in! I know, I know.. we could have used the CharacterStats filter, but we are learning here, and CharacterStats is a Howto of it's own.

Grabbing a trusty copy of the protocol (Be sure to bookmark it), find out what packet comes when you log in. Actually, there are quite a lot. Each item in your pack, all the people around you, and of course F7B0 - Login Character.

<Edit by Minuo>
The protocol URL is http://sixpinetrees.com/AC/Decal/Protocol/Protocol.asp
</Edit by Minuo>

Now, F7B0 is in hex. So treat it like one. The way you do this in VB is to put &H****& around it. So, F7B0 = &HF7B0&. As another tip, if you want to make a string out of a hex, use the Hex() function. Technically, you could put it into a long and then do a str(), but your number is going to be in base 10 (decimal, counting on your fingers) and you really need to keep thinking in Hex.

We can check for that message type one of two ways, If statements or Select Case statements. If we are only looking for one type of packet, an If works, but Case's are much better.

Code:

Select Case pMsg.Type
Case &HF7B0&: ' Login Character
End Select



Now that we trapped our Login packet we need to grab the contents out from it. The data is contained in members. Normally, members aren't any more complicated than stating what you are looking for. We'll examine some of the complexities later.

Using the protocol document, we see that the characters name is called "name". So, we just need to look for member("name"). It is CASE SENSITIVE! So, keep an eye out for capital letters.

Code:

...
Case &HF7B0&:
pluginsite.writetochatwindow "Hiya, " & pmsg.member("name")
...



Simple? You bet. Ready for a tough one? Let's compliment the user on their choice in Allegiance. Now, looking at how a players allegiance information is handled, we see that there is a vector, and to make it worse, you have to check a flag mask to see if the vector piece is the person's patron or monarch. Calm donw... breath.

A vector is a fancy word for array in this instance. And a Mask is just a compressed boolean value.

From the protocol, it looks like allegiance information is a vector called "section5" and section5's count is in "count5". That means that we just need to loop through section5 count5 times looking for the monarch key. And from the protocol, the monarch key is &H18&. To figure out if the key you are looking that has a mask of &H18&, you will want to AND the two values. AND performs a logical bitwise comparison and leaves the matching bits. So, &H4& AND &H7& is really represented in binary as 0100 AND 0111, which equals 0100. I'll recap that like this:

0100
0111
----
0100 <-- Only the second bits from the left match

Code:

...
Case &HF7B0&:
pluginsite.writetochatwindow "Hiya, " & pmsg.member("name")
For Counter = 0 To (0 & pMsg.Member("count5")) - 1
If pMsg.Member("section5").Member(Counter).Member("key") = &H18& Then
pluginsite.writetochatwindow hex(pMsg.Member("section5").Member(Counter).Member("value")) & ", what a great guy!"
end if
next
...


Huh? Hex(pMsg.Member("section5").Member(Counter).Member("value"))? First, the reason I tagged the Hex() around it was because I know from experience that it doesn't contain the name of the person. It contains the GUID. Each object has a GUID, it's just an unique Double Word number of an Item. Just remember that.. every object(people, creatures, doors, weapons) has a GUID. The other question I bet you have is, why so many members?

When you play with vectors, you have the main member type. In this case, it is section5. Then, you have it's offset, which is our Counter. Then you have th data in that offset, which is key and value.

Summary:

And there you have it. You just learned how to handle packets and absorbed complex parts that take many others months to figure out. While you most likely will want to use Filters for ease. Never underestimate doing it yourself.
_________________
- Navi - Navi II - Navi III -
http://www.saigumi.net
http://navi3.sourceforge.net

[Hazridi]

Just some clarifications:

the type 'Double' in VB and 'double' in C/C++ are the same. it is a double precision floating point variable, that stores twice as much data as a single precision floating point variable (float in C/C++, Single in VB). Singles hold 4 bytes, and doubles hold 8 bytes as I recall.

The type DWORD is a double word. It stores 4 bytes of data, and is just an unsigned long.


I know a lot of you people reading Saitoh's excellent howtos are new to programming, so here's a tip: Learn the primitive types and how they work. This will help you understand what you're doing.

When you use &Hsomething& in VB... what it is doing is making a LONG consant. That's what the ending & does, it signfies that the variable is a long. &H10 is valid syntax, but it doesn't do quite the same thing as &H10&.

[Guest]

The protocol URL is http://sixpinetrees.com/AC/Decal/Protocol/Protocol.asp


this page can not be found

[The White Wolf]

new protocol location is http://decal.insanity-inc.org/protocol
_________________
W O L F of Wintersebb
I don't have an anger problem, I have a DUMBASS problem!
My Decal plugins and stuff - http://www.the-lonewolf.com