UDPClient (3.0) January 07 2007

by Lewis A. Sellers

Description

This UDPClient COM object allows you to talk to anything on the Internet that uses the UDP communications protocol.
UDP is part of the TCP/IP suite which powers the internet and is the "little brother" of the more famous TCP. UDP is an "unreliable connection-less" packet protocol. This means you can send small "post-it note" like messages very, very quickly between machines but there is no guarantee that the message will ever arrive. Compare this to TCP, which is slower to startup, but any data you send is automatically resent if lost along the way. TCP also lets you send a stream of essentially unlimited size, where UDP is limited to about 65,507 bytes at the most.
A COM object (for those of you who are using this software who are not web developers but hardcore gamers) is a type of .DLL. This particular type is the kind that makes up most of the code that powers the Windows Operating System itself. They are essentially self-contained ("encapulated, object-oriented" in tech-speak) programs. Many of the applications you may use (the .EXE files) will make use of COM objects that it brings with it or that are included with the Windows Operating System.
Primarily the only things of real importance these days that use UDP are:
Game servers(!) such as: Quake, Half-Life, Unreal, Wheel of Time, Baldur's Gate, Diablo, Star Trek : Elite Forces, et al (well, perhaps not ALL, but most the ones that anyone cares about).
Hardware-based routers (i.e., CISCOs).
Packet messagers such as ICQ.
For that reason most of the example code you will find here deals with the interrogation of on-line game servers. (Did I hear a small cheer go up?)
Understand that this COM object provides only the elemental, base functionality you need to talk to these UDP servers. As for what you're supposed to say to them and what do the messages they send back mean, well... that's a subject for several heated on-line forum discussions and a half-dozen small project groups to ferret out. I've included example scripts written in ColdFusion meta-language (i.e, the files with those .cfm extensions) that show exactly how to talk to all the games I know how to talk to. You'll have to figure the rest out yourselves. Start by reading a games' official (or unofficial) protocol documents, if any... the rest is up to people willing to pester developers for the information or hackers with packet sniffers and a little imagination.

TermsOfUse

This software is Copyright (c) 2000, 2001 by Lewis A. Sellers. It is not public domain, nor is it GPL'ed, but it is very close. As long as you do not modify any files in the archive, nor add to them, nor delete any of them, and do not charge for access to said archive you may redistribute the archive as you like.
You may use this software as-is with any software you wish, so long as said archive is included unmodified with proper credits and link to it's homesite is included also (http://www.intrafoundation.com/udpclient.html).
You may modify and use the source code as you like -- with the understanding that if you do, you still have to include the original, unaltered archive as well as the aforementioned credits and link.
You may use this software in commerical applications, whether closed-source or open-source so long as the aforementioned unaltered archive is included with the application and the aforementioned creditation and hyperlink are included.
If this software is used in a released project or included in a publication you are to make reasonable efforts to contact the author and notify them as to such. The author of this software has a primary email address of: lsellers@intrafoundation.com.
You use this software at your own risk.

Platform Specifications

This COM object was designed on and for Windows 2000 Professional and Windows XP Professional. It has not been tested under Windows 95, 98, ME or NT 3.51/4. Nevertheless, it may work under some of them.
Additionally you most typically will need either Adobe ColdFusion (previously owned by Macromedia, and before them Allaire) or Microsoft ASP installed. If you don't know what either of these are... then you're going to need to make friends with a geeky web developer somewhere to help you.
You should be able to use the COM from:
Adobe ColdFusion
Microsoft ASP
PHP
Any other engine or compiler that can use COM objects.

Version History

• version 3.0     January 07 2007
  

  It's been a while. I mostly develop on Macintosh computers these days, so it's a little odd having Visual Studio up in an RDC on one of the monitors of my Mac system. Nevertheless...
  The short: Was asked (paid) to rework parts UDPClient for an engineering project. While dusting the old thing's source code off I was a little surprised to find part of the source was missing from last archive put out. Apologies. Had to go off into the file cabinet hunting for the last backup myself for an hour or two. So, as far the code base goes 3.0 is based upon a mix of the 2.1 and 2.0 sources, with a few additional enhancements. It is compiled under MS VS C++ 6SP6 W/ processor packs.
  Changes: • v3.0 adds the OpenFromPort function. (Verified by the packet sniffer Ethereal/Wireshark). • Various other cosmetic and debug-level changes were made. • Also adds back the complete source code. • Changed several of the examples.
  Note of interest: For the most part I edited all the code on my Mac in XCode 2.4. :) Only dropped into rdesktop to compile (and execute the test harness). BTW, I added a command line test harness app called "harness". (See the folder of the same name.) It is for testing the underlying udp class seperate from a web server. I mention this as it can be useful for rapidly constructing tests of various protocols you may be trying to interface to without having to go through the much heavier dev cycle with a web server in your way.

• version 2.1     November 05 2004
  

  Updated the C++ classes it shares with several other projects, so recompiled. Cleaned up for the relaunch of the Intrafoundation web site.

• version 2.0     July 06 2004
  

  Never released 2.00 but did today after a few tweaks and cleaning up the documentation. The property "error" has become "Log" and a "ClearLog" function has been added.
  NOTE: For compatibility with ColdFusion all "boolean" values are passed as "long" (Once again. Now I remember why it was originally doing that -- ColdFusion can't handle boolean's with COM objects.)

• version 10.1alpha     August 22 2001
  

  Some folks at http://www.cnyonlinegamers.net asked if I could list server game stats. What the hell. Was going to have to write something similiar for another project soon anyway, sooo... Recreated the projects files.

• version 1.9     September 13 2001
  

  Tightened up a lot of the udp class (the low-level class part of the COM). Also straightened up several script bugs or oddities of the protocols in the scripts, especially with unreal. Added some code by steelvalor.

• version 1.8     September 09 2001
  

  Some of the scripts were upgraded, especially gamescry and unreal. Added some experimental IP and Port packet features, but you probably shouldn't try to use them.

• version 1.7     September 06 2001
  

  Duh. Forgot to add a PING function. Fixed. Now every send/recv cycle has ping automatically computed for you.

• version 1.6i     September 05 2001
  

  Fixed an oddness in the half-life script that misreported mod byte sizes.
  Also added GAME SCRY ;-> page.

• version 1.5     September 04 2001
  

  Munged up the half-life code. Fixed. Misc other.

• version 1.4     September 02 2001
  

  Cleaned up examples.

• version 1.3     September 02 2001
  

  Cleaned up packet functions. I haven't as yet used the "packet" write/add functions at all so it's a guess as to whether they actually work or not.

• version 1.2     August 31 2001
  

  More cleanup.
  Binary field structuring/destructing functions where added to handle half-life. Unlike all the other server query setups which send their data in clear text, half-life sends it's data in binary c structs. Efficient, but annoying to deal with.
  While redesigning the website I'd completely forgotten that I'd decided not to make tcpclient/udpclient GPL. Why? Because some folks want to use them in commerical apps and then sell the apps. I really don't give a damn what most people do with this code as long as they make good use of it and don't try to claim that THEY wrote the original code (people do that sometimes). If there was a GPL that allowed use in commerical apps without having to reveal the code that others wrap around it then that's what I'd use. And how I'll assume you'll use it.

• version 1.1beta     August 30 2001
  

  General cleanup to code and docs. Added Unreal derivitives. Looking for Baldur's Gate, etc info.... (btw, before you ask: I don't know what the yellow flower symbol is about. It just wanted to sit there so I let it.)
  Still reworking those damn docs.... reading the working scripts would probably be more informative.

• version 1.18     April 23 2004
  

  1. Fixed inversion of returns/parameters notation in documents.
  2. Added daytime and time protocol examples.
  3. Added new Log class and extra debugging info.
  4. Misc little tweaks to clean up code a bit.
  5. Oh. Important. Fixed a bug (an oversight actually) that had "open" returning a number instead of a boolean like was stated.
  Thought about leaving it that way, but couldn't resist fixing it. The downside is this breaks some ASP code that's looking for a number to be returned. It now returns "True" or "False" as a boolean should.
  6. Added instance and instances properties.
  7. Added an application level thread-safe mutex. (So the COM can be used in application scope of CF or ASP without too much crashing.)
  8. Changed version to 2.00 when I realized I had to change the COM interface for the additional functions. Before 2.00 all versions used the interface "Intrafoundation.UDPCLient.1". This version uses "Intrafoundation.UDPClient.2" which is slightly different (new functions and a change to the open functions' return type.)
  9. Added high resolution timer code.
  10. Optimized udp Revc function.
  11. Added sendpackets and recvpackets stat.

• version 1.17     November 20 2003
  

  UDPClient Author: Eric Shufro URL: http://eric.shufro.com Created: 9/6/2003 9:44:54 AM Maybe im doing it wrong, but addpacketstringN chr(128-142) excluding 129 and 141 dont work. Nor does chr(145-159) excluding chr(157). Very odd. Instead the udpclientcom sends chr(0) when any of those listed numbers that dont work appear. All other numbers between 0 and 255 work perfectly. There are 27 numbers that will not send and generate 0`s instead. Any ideas?

• version 1.16     July 20 2003
  

  Minor tweak to addpacketstring and addpacketstringN. Cleaned up some docs.

• version 1.15 G     May 01 2003
  

  A few minor fixes to docs and code.

• version 1.12     November 15 2001 (288 KB)
  

  My ASP is a bit rusty, but... I added ASP examples for Half-life, RTCW, Quake3, STEF, etc after a bit of prodding by Sakke Huhmarniemi.
  Fixed packetlength and packetposition bug that let "junk" number show up in asp if you weren't connected.
  Added packetEOF property.

• version 1.11a     October 08 2001
  

  SteelValor sent over some spare gaming gear for the gaming-list help the other day. The attack v-1 gaming mouse pad is *nice*. I mention this because I was trying it out in the new Quake3-based Return to Castle Wolfenstein (yes, I'm addicated to it -- so are a lot of us)... and I kept killing this poor guy named captureman after the other folks left the server. Over and over and over. He finally just disconnected. I feel bad about it. Poor guy. These pads are evil. /-)
  A few slight script changes. Someone gave me an old copy of Tribes 1.0. Apparently the code doesn't work very well with it or the 1.11 patch. Hrm.

• version 1.11     October 02 2001
  

  Cleaned up the cfm a bit. Added packetstringN, addpacketstringN and packetstringC functions to COM to handle visualbasic-style strings with prepended length variables. This was done to more easily deal with the format of Starsiege: Tribes (you could have simply used a loops of packetchar's).
  Added some experimental Starsiege: Tribes code. Since I don't actually own a copy... it's somewhat of an educated guess as to whether it works.

• version 1.10     September 21 2001
  

  Added wolfenstein test (same as quake3). Mulled over adding high-performance functions to batch send/recv for gamescry. Forums at steelvalor.
  My game name, BTW, is TommyRaven or sometimes LT.TommyRaven.

• version 1.0alpha     August 29 2001
  

  Started working on it again in the afternoon. Pretty much had it working later that night after trying a few different strategies. K.I.S.S. /-) The documentation is competely bogus at the moment... leftover from the tcpclient project folder. It's my experience that writing technical docs usually takes longer than writing the project itself.

• version 0.0     August 22 2001
  

  1999 - 2001, shadow thought for tcpclient for years

[Manual friendly version]