BN# - Beta 1

[MyndFyre]

BN# (that's "BN-Sharp") has reached Beta 1!

If you haven't yet heard of BN#, it's a Microsoft .NET Framework-based utility library meant for simplifying the process of connecting to Battle.net.  It's a highly-optimized, highly efficient, object-oriented, and extensible drop-in for most Battle.net projects.  Oh, and I almost forgot to mention -- it's open-source.


What's new in Beta 1?
New Features

• Most appropriate classes has have WCF attributes applied to them and can be serialized with a DataContractSerializer.
• Added the ability to request user profiles.
• Friends support was added in this release
• BN# exposes a new event called EventExceptionThrown.  The purpose of this event is to allow a host application to know when a specific plugin or feature set is causing an error and handle it gracefully.  JinxBot will handle this condition, for example, by allowing the user to unload plugins on-demand if they are causing many exceptions.
• Additional clan support was added; BN# now understands and supports events for clan functions such as formation, chieftan change, new formation searching, and disband.  Corresponding new functions include BeginClanCandidateSearch, InviteUsersToNewClan, RespondToNewClanInvitation, DisbandClan, and DesignateClanChieftan.  Corresponding new events include ClanCandidatesSearchCompleted, ClanFormationCompleted, ClanFormationInvitationReceived, ClanDisbandCompleted, ClanInvitationReceived, ClanInvitationResponseReceived, ClanRemovalResponse, LeftClan, and ClanChangeChieftanCompleted.
• A new interface is supported for the ordering of packet parsing priority.  This would allow, for example, a moderation plugin to require that ChatEvent packets are processed first (to receive UserJoined events).  To support this functionality, implement the IPacketPriorityProvider interface in the BNSharp.Plugins namespace, and call BattleNetClient.RegisterCustomPacketPriorities/UnregisterCustomPacketPriorities.
• A demonstration project of a JinxBot plugin for adding MCP (Realm Server) support to BN# is available in the repository.  It obeys some JinxBot contracts, but extends BN# to include handling for realm servers.
• A new method was added to BattleNetClient called CreateAccount().  If the login process fails, you can attempt to create the account by calling CreateAccount; it will use the information provided in the Settings object (this information can be changed dynamically at run-time).  CreateAccount will result in the AccountCreated or AccountCreationFailed events to be raised; if AccountCreated is raised, the client will automatically log in.
• The client no longer automatically disconnects because of an account login failure.  (CD key or versioning failure still results in an automatic disconnect).
• To support the no auto-disconnect policy, a new method was added to BattleNetClient called ContinueLogin().  This method allows the user to change the Settings object to modify the username and password of the desired login and then begin logging in again.

Breaking Changes

• By default, BNSharp requires support for .NET 3.0 because it references System.Runtime.Serialization version 3.0.0.0.  For details on compiling without support for WCF data contract serialization, see the article Compiling BN# for .NET 2.0 on the JinxBot wiki.
• IBattleNetSettings now requires a new property, '''PingType''', which allows the connection to attempt to drive a 0ms, -1ms, or standard ping type.  Old code will need to add this property to the IBattleNetSettings implementation class.
• Users now automatically have a Stats property that contains a reference to a class derived from UserStats.  This change is breaking and will impact code written for an older CTP release.  If using the latest code, this will be compatible with handling code from r15 or newer.
• The LoginFailed event is no longer prototyped as EventHandler but LoginFailedEventHandler.  The LoginFailedEventArgs class contains contextual information about the reason for login failure.

Non-Breaking Changes

• BN# includes the attributes used for data contract serialization as internal, stub attributes that will enable cross-versioning compatbility.  For more information, see the article on compiling for .NET 2.0.  This also removes the #if !NET_2_0 conditionals wrapping the attribute declarations throughout the data code.
• BN# now guarantees events are fired in the correct order by creating additional threads and event queues.  This should increase the reliability of the order of events when joining a channel, for example.  (Previously, joining a channel could cause a user to be listed as joined before the ChannelJoined event fired due to a race condition, which could cause the user to be added to the user list and then removed).
• Events on a BattleNetClient now have dedicated threads for Normal- and Low-priority event handlers.  High-priority events are still executed on the Parse() loop.  All Normal-priority event handlers are executed before outstanding Low-priority event handlers are executed.
• Added a new Position property to the MBNCSUtil DataReader class.
• Modified the non-Lockdown version of CheckRevision to use approximately 25mb less of memory allocations and reallocations, saving 3-4 gen-0 garbage collections.  The Lockdown version of CheckRevision uses significantly less memory and will be updated in a future version of BN#.

Bug fixes

• Corrected a defect in which a Warcraft 3 statstring would be incorrectly parsed due to a server defect.
• Corrected the IBattleNetEvents interface and the EventSink interface to expose all events
• Guarantees correct detection of Disconnected events.

Get BN# from the above link and check out the online documentation!

[Chavo]

Funny, I was about to pm you saying I had some time to help with this.  Do you have your JinxBot preview that uses BN# working as well?

[MyndFyre]

Funny, I was about to pm you saying I had some time to help with this.  Do you have your JinxBot preview that uses BN# working as well?

Yes, I have it working, but it's not ready to make a full release just yet.

[Camel]

Packet prioritization? That sounds like a disaster waiting to unfold!

[iago]

Packet prioritization? That sounds like a disaster waiting to unfold!

I did something similar to that in JavaOp2, and it worked perfectly.

Explain the "disaster"?

[MyndFyre]

Packet prioritization? That sounds like a disaster waiting to unfold!

How so?

Threads of execution:
* Receive() loop - gets data one packet at a time from Bnet, puts packets into a priority queue
* Parse() loop - gets packets out of the priority queue, hands them off to the parsing handler function, calls the high-priority event handlers, and enqueues the event for lower-priority handlers.
* Normal- and Low-priority event handler loops - fire the normal- and low-priority event handlers.

The idea is that you can say something like, SID_USERJOINED is higher priority that SID_CHATEVENT.  So the handlers for SID_USERJOINED will always be processed first.

Why does that sound like the potential for disaster?

[Camel]

Why would you want to process the packets out of order? You shouldn't display a user joining before a user chatting unless that's the order that you recived the packets in, otherwise the user could be mislead to think that the person who joined saw the chat.

I can't think of any case where it's advantageous to prioritize packets, but I can think of several cases where it could lead to invalid state - for example, if you parse a user leaving the channel before entering, then the bot will show the user in the channel when he isn't.

[MyndFyre]

Why would you want to process the packets out of order? You shouldn't display a user joining before a user chatting unless that's the order that you recived the packets in, otherwise the user could be mislead to think that the person who joined saw the chat.

I can't think of any case where it's advantageous to prioritize packets, but I can think of several cases where it could lead to invalid state - for example, if you parse a user leaving the channel before entering, then the bot will show the user in the channel when he isn't.

Since the EID_SHOW/EID_JOIN/EID_LEAVE packets are all handled as SID_CHATEVENT (0x0e) they can't be processed out of order.  Looking at my previous post, I misspoke to say that within-packet-ID events could be handled out-of-order.

I envision a moderation plugin where things like SID_CHATEVENT are infinitely more important to be parsed than, say, SID_CLANMEMBERSTATUSCHANGED, SID_FRIENDUPDATE, or other miscellaneous packets of that nature.  I'd certainly want moderation events to have higher priority than things that aren't important to a client whose sole purpose was moderation.

[Camel]

Why would a moderation plugin process friend updates?

I don't see any condition where the prioritization could ever potentially be useful.

[MyndFyre]

Why would a moderation plugin process friend updates?

The core processes every packet.  It doesn't just say "Oh look, a packet, but fuck it!"  But a moderation plugin might want the core to process that packet a little bit further down the pipe - you know, when all of the chat events are done being processed?

I don't understand why you're being such a hard-ass about it.  It's optional, the default setting is "everything-normal," and nobody's making you use this.

[Camel]

The moderation plugin doesn't process friend updates, and therefore doesn't care whether friend updates are processed before or after chat events.

I don't think I'm being a hardass, and I'm certainly not trying to depreciate the cool factor of it - it is something that is interesting and probably useful to someone somewhere; not in this context, though. There is, IMO, no valid argument for processing BNCS packets out of the order from which they came off the wire. It simply doesn't have the potential to be useful, as guaranteed by the fact that the only packet that requires any substantial amount of power to process is ineligible for a variable priority.

Don't take what I'm saying the wrong way, I am genuinely interested in this kind of thing. Hopefully I'll have some time soon to sit down and actually take a look at how you did it, since I can think of at least one application I'm working on where it would be advantageous to do something similar (that is, prioritizing a potentially large queue of packets).

[MyndFyre]

The moderation plugin doesn't process friend updates, and therefore doesn't care whether friend updates are processed before or after chat events.

You're not hearing me.  The core by default fires off each event as it is retrieved from the wire.  If a plugin wants to make a connection highly moderation-centric, then it could tell the core to process the packets out-of-order.  The processing of every packet happens regardless of whether event handlers are registered to listen to the relevant events.

The ultimate goal for this is that a JinxBot application can be as rich as any typical client without sacrificing potential security features such as channel flood handling.  I don't know whether that will become an issue.  But I don't really see this becoming dangerous, which was, as I feel obliged to point out, your original criticism.

[Camel]

Are you saying that the core processes internally the packets as they come off the wire, but then might fire the events out of order to one particular plugin? As long as the core's internal state is modified in the order that packets come in off the wire, that seems reasonable; I must have misunderstood how you are doing it.

I don't recall using the word dangerous


[edit] After looking back at your original post, it sure does sound like you're parsing packets out of order upon request. What happens if one plugin requests that packets are parsed out of order, but another plugin doesn't properly handle some corner case like a user being promoted on the friends list before he's added to the friends list?

[MyndFyre]

[edit] After looking back at your original post, it sure does sound like you're parsing packets out of order upon request. What happens if one plugin requests that packets are parsed out of order, but another plugin doesn't properly handle some corner case like a user being promoted on the friends list before he's added to the friends list?

Then something breaks.

It's up to the user to handle these situations.  The core can certainly get out of state by handling a FriendRemoved event before a FriendAdded event if FriendAdded is set to low priority and FriendRemoved is set to high priority, and somehow the messages to add and remove a friend are sent to Battle.net in rapid enough succession that the core has to enqueue them.  I'd hope that someone wouldn't be stupid enough to do that, but if you really want to......

[MyndFyre]

I released Beta 2; it was a bugfix release and offers a new utility class that gets about halfway there to the full implementation of Warden.  This functionality will be rolled into MBNCSUtil proper soon as well.

New Features

• Support for Warden has been partially implemented in the BNSharp.MBNCSUtil namespace in the class WardenEncryptionContext. The end-user is still required to implement the IWardenModule interface. However, developing the implementation should be significantly improved. This contribution was a joint effort by Warrior[x86] and MyndFyre.
• Several changes that were related to Warden have been implemented and rolled into the BattleNetClient class. These issues did not necessarily prevent correct implementation of Warden, but they did not follow the documentation and were corrected in this release.
• Corrected an issue that caused an exception on the parsing thread during friend updates on Starcraft and Brood War.

What's coming for Beta 3

• Support for Warcraft III profiles and clan information lookups.
• Built-in support for ad messages.
• Support for setting e-mail interactively during login.
• Sanity checking for passing the IBattleNetSettings interface.
• The ability to change the server on ConnectionBase without reinstantiating the class.
• Binary Join Channel command function.
• Support for chat message throttling via the ICommandQueueProvider interface.
• All remaining internal connection status strings will be removed into the localizable file format.

[Joe]

Two quick bugs.. looks like BattleNetClient.Channel isn't emptied on channel switches, and as I told you over AIM, there's a typo in the event WardentUnhandled.

[MyndFyre]

Good catch on channel join!  Please report bugs here.