[This is preliminary documentation and is subject to change.]

VERY IMPORTANT! If you do not intend to use BN# as a development platform, it is recommended that you use the standard MBNCSUtil library instead of BNSharp.dll. The version of MBNCSUtil included with BN# is optimized to work with the BN# library and contains dependencies that cannot be handled if you do not work with the BN# API.

The BNSharp.MBNCSUtil namespace provides managed types for the implementation of Battle.net logon authorization as well as a number of other utilities to support Battle.net development.

This library should run on an x86- or x64-based Windows system. MBNCSUtil now includes Windows-specific API calls for the MPQ file handling (MBNCSUtil.Data) and Lockdown CheckRevision calls. Other code should function normally on systems with the Common Language Infrastructure.

This code was originally based upon Eric Naseth's (shadypalm88's) BNCSUtil 1.0.4, Ron Bowes' (iago's) various implementations in Java and C, and Robert ONeal's, from whose code most of the Lockdown implementation was based. However, most code is original C#, unless otherwise noted, by Robert Paveza (MyndFyre).

This library is licensed under a modified version of the BSD license as of version 1.2.0.4. This license supercedes previous licenses of this library for versions 1.2.0.4 and newer. Older libraries will continue to be licensed under their old license or, optionally, the new BSD license. For more information, consult the LICENSE.TXT file that should have accompanied this file.

This library includes binary code under license from Ladislave Zezula. Separation of this library from the binary code is not permitted, nor is distribution of the binary. Please obtain your own license for StormLib by downloading it from www.zezula.net.

Versioning Information

MBNCSUtil v2.0 is a relatively major departure from previous versions. COM support is no longer included, and the library is offered only for .NET 2.0. Furthermore, assemblies are versioned for a specific processor architecture. If your application is going to support both x86 and x64, it is highly recommended that you include MBNCSUtil as a project within your project solution, add it as a reference to your project, and ensure that you have x86 and x64 builds. For more information on how to do this, consult the Visual Studio documentation.

Changelog

Version	Changes
Planned (Future) Updates	Installation (.msi) utility and integration with Visual Studio's help system. BNLS integration, due for version 2.2. BLP and BLP2 image processing, due for version 2.1.
2.0.5.18 Final [documentation] [code] Binaries: x86 Debug x86 Release x64 Debug x64 Release Current SVN Revision: 21	Subversion URL: https://svn2.hosted-projects.com/robpaveza/mbncsutil Trac URL: https://www2.hosted-projects.com/trac/robpaveza/mbncsutil/wiki/WikiStart Corrected a series of issues with the NLS class.
2.0.4.17 BETA 2 [documentation] [code] Binaries: x86 Debug x86 Release x64 Debug x64 Release Current SVN Revision: 15	Did you know that MBNCSUtil includes a number of additional tools used in the development and testing of MBNCSUtil? These tools and utilities are sample code that indicate how to use some of MBNCSUtil's features, including a command-line tool for downloading files from BnFTP, extracting a file from an MPQ, and even a rudimentary client used to ensure the Lockdown implementation works with class based on JinxBot's ConnectionBase class. These files are all available through the Subversion repository at https://svn2.hosted-projects.com/robpaveza/mbncsutil/. You should log in with the username mbncsutil_anonymous with no password. Need a Subversion client? I use TortoiseSVN. Added event/status support to the Battle.net FTP downloading scheme. To obtain status updates, listen to the BnFtpRequestBase.FilePartDownloaded event. Corrected an issue in which approximately 7.5% of lockdown calls would result in failure. The bulk test tool reports 100% success. If you encounter a revision check failure, please e-mail MyndFyre@valhallalegends.com with the value-string and lockdown MPQ file parameters (as well as the product). Corrected documentation that provided a sample for extracting files from MPQ archives. Corrected an issue reported by Homerlan and iNsaNe (at the vL forums) in which the NLS class was generating a NullReferenceException because the k field had not been initialized to a value. Corrected an issue reported by Chriso.de (at the vL forums) in which the NLS class was generating an IOException because certain username values returned shorter names when using Encoding.ASCII.GetByteLength than the actual length of the username. Explicitly added a NotSupportedException when CheckRevision.ExtractMPQNumber is called with a Lockdown MPQ filename. Corrected an issue reported by Joe[x86] in which the MPQ loader would mistakenly load the 64-bit MPQ support DLL when operating within a 32-bit process on Win32 platforms not running 64-bit OSes.
2.0.3.16 BETA 1 Service Release [documentation] [code] Binaries: x86 Debug x86 Release x64 Debug x64 Release Current SVN Revision: 9	A bug was identified in the way the LockdownHeap class (part of the MBNCSUtil.Util namespace, which is not a public namespace) was marshaling data to the unmanaged heap, which was cauing 100% failure rates on lockdown. This issue has been corrected. Please note that the downloadable documentation file has not been updated for this service release, as the API has not changed.
2.0.3.15 BETA 1 [documentation] [code] Binaries: x86 Debug x86 Release x64 Debug x64 Release	Lockdown CheckRevision is now supported for Starcraft and Warcraft II: Battle.net Edition. This is a pre-release version of MBNCSUtil 2.0 that previews the MPQ, BnFTP, and Lockdown Checkrevision functionality of MBNCSUtil 2.0. Tests indicate that Lockdown currently incorrectly calculates the revision check 7.4% of its uses. IMPORTANT - MBNCSUtil 2.0 does not support the .NET Framework 1.x; clients that wish to use MBNCSUtil 2.0 should target the .NET Framework 2.0. MBNCSUtil is now hosted in a Subversion repository. Point your favorite SVN client at https://www2.hosted-projects.com/robpaveza/mbncsutil/trunk/ to download the latest bits. (Note that the SVN repository is updated much more frequently than the stable build list; for stable builds, be sure to download the software from the official site). Along with Subversion, there is now a Trac wiki and bug tracker. Visit it at https://www2.hosted-projects.com/trac/robpaveza/mbncsutil. Both Subversion and Trac require authentication; use the username mbncsutil_anonymous with no password. MBNCSUtil 2.0 includes the ability to open MPQ archives! See the MBNCSUtil.Data namespace for implementation details. If you retrieve the solution from Subversion, you will find a project called mmpq in the trunk; this project demonstrates opening an MPQ and retrieving its listfile. MBNCSUtil 2.0 includes an integrated ability to download files from Battle.net via the proprietary BnFTP protocol. See the MBNCSUtil.BnFtp namespace for implementation details. If you retrieve the solution from Subversion, you will find a project called mbnftp in the trunk; this project demonstrates downloading files from the BnFTP service.

Classes

	Class	Description
	BncsPacket	Completes a DataBuffer implementation with the additional data used by the BNCS protocol.
	BncsReader	Completes a DataBuffer implementation with the additional data used by the BNCS protocol.
	CdKey	Provides utilities for decoding and otherwise validating CD keys of Blizzard products. This class cannot be inherited.
	CheckRevision	Encompasses any revision check functionality for all Battle.net games. This class cannot be inherited.
	DataBuffer	Operates as a data buffer for network and file output.
	DataFormatter	Provides functions for printing bytes to various output devices. This class cannot be inherited.
	DataReader	Operates as a buffered data reader for network and file input.
	NLS	Supports the New Logon System's SRP (Secure Remote Password) authentication system as well as Warcraft III server signature validation. This class cannot be inherited.
	OldAuth	Calculates hash values for data using the old login-system checks.
	WardenEncryptionContext	Handles the encryption and decryption of Warden modules for a given connection.
	XSha1	Provides an implementation of Battle.net's "broken" (nonstandard) SHA-1 implementation. This class cannot be inherited.

Licensed under a modified version of the BSD license; see associated license for licensing terms. Blizzard, Battle.net, Starcraft, Warcraft, Warcraft II: Battle.net Edition, The Tides of Darkness, Into the Dark Portal, Diablo, The Lord of Destruction, Brood War, Warcraft III: The Reign of Chaos, The Frozen Throne, World of Warcraft, and The Burning Crusade are trademarks or registered trademarks of Blizzard Entertainment Inc. in the United States and/or other countries. Other marks may be the trademarks or registered trademarks of their respective owners.

Send comments on this topic to myndfyre@valhallalegends.com