Create a graphical alternative to NET SEND using the Win32 network API
[Editor's Note: VB Solutions is about using Visual Basic (VB) to build a variety of solutions to specific
business problems. This column doesn't teach you how to write VB, but how to use VB as a tool to provide quick,
easy-to-implement solutions that you can use right away.]
Windows NT's NET SEND command provides a useful way to send network messages; however, you have to run it
from the NT command prompt. This month, I present an alternative to NET SEND that lets you send network messages without
leaving NT's graphical interface. The NetMessage Visual Basic (VB) utility is a graphical equivalent of NET SEND.
Instead of going to the NT command prompt, you can simply run NetMessage from your NT desktop or from the Start menu.
Screen 1, page 184, shows the primary interface for NetMessage.
Using NetMessage is easy. The utility prompts you for the name to send a network message to and provides a
multiline text box in which you enter the message's text. To send a message to a networked system, you enter the
destination user's system name or logon name in the To box. NetMessage lets you either manually enter the name or select
it from a drop-down box. You can also send a broadcast message to all users in your domain or other domains by selecting
the domain name from the drop-down box, as shown in Screen 2, page 184, or by entering it manually. After entering the
recipient's name and message text, you click Send to send the message. Screen 3, page 184, shows an example of the
resulting pop-up message displayed on the target system.
The target system must be running the NT Messenger service to receive and display a network message. NT's Messenger
service is started by default in most NT installations. The NetMessage utility sends the message via NetBIOS as the
network transport.
Inside NetMessage
Now that you've seen how NetMessage works, let's build it. Because the NetMessage utility performs network calls,
you might think building it requires complicated C communications coding and a knowledge of system internals. Not true.
NT provides a rich set of network APIs, and you can call most of them from VB. By calling these APIs, your VB programs
can access a variety of networking functions unavailable in standalone VB. The NetMessage utility uses NT's Win32
network API to handle the networking parts of the application.
The Win32 network API is in NT's netapi32.dll. This DLL contains many functions, but the NetMessage utility uses
only three of them: NetServerEnum, NetWkstaGetInfo, and NetMessageBufferSend. Like several other VB Solutions utilities,
NetMessage uses NetServerEnum to retrieve a list of networked systems--specifically, a list of all NT systems in the
network. The NetWkstaGetInfo function retrieves the names of the network domain and local system--both of which
are required to send a message across the network. The NetMessageBufferSend function sends a message across the network.
Because the functions contained in netapi32.dll are not built into VB, you must declare them before you can use
them. (I explained the NetServerEnum function in the November 1996 VB Solutions column). The VB declaration for the
NetWkstaGetInfo function is
Declare Function NetWkstaGetInfo _
Lib "Netapi32"
_
(ByVal sServerName$, _
ByVal lLevel&, vBuffer As Any) _
As Long
NetWkstaGetInfo is a fairly simple function that takes only three parameters. The first parameter is a Unicode
string that contains the name of the server on which the function will be executed. A null string specifies that the
function will run on the local system. The second parameter determines the level of information the function will
return. NetWkstaGetInfo returns several different types of information depending on the value you specify in this
parameter. However, the NetMessage utility uses only the most basic information, specified by passing the value 100. The
third parameter is a pointer to a buffer that contains a data structure filled with the network information that
corresponds to the information level specified by the second parameter.
The VB declaration for the NetMessageBufferSend function is
Declare Function _NetMessageBufferSend _Lib "Netapi32"_
(ByVal sServerName$, _
ByVal sMsgName$, _
ByVal sFromName$, _
ByVal sMessageText$, _
ByVal lBufferLength&) _
As Long
The NetMessageBufferSend function's first four parameters take Unicode strings. The first parameter contains
the name of the server on which the function will be executed. The second parameter contains the message recipient's
name. The third parameter contains the message sender's name. The fourth parameter contains the text of the message to
be sent. The fifth parameter, a long integer, identifies the length of the message to be sent.
Because the NetMessageBufferSend function is declared in a DLL, all the string parameters are declared with the
ByVal keyword. Although ByVal ordinarily causes VB to pass a parameter's value, this keyword works differently for
passing string parameters to an external DLL such as netapi32.dll. Using ByVal to pass strings to functions contained in
external DLLs causes VB to convert the strings from VB string format into the C string format required by most DLLs,
including netapi32.dll. The fifth parameter also uses the ByVal keyword, but because this parameter contains a
numeric variable and not a string, ByVal works as you'd expect: It causes VB to pass the value of the numeric variable,
rather than passing a pointer to the variable.