==============================================================

   Copyright 1994  Northeast Data Corp.  All Rights Reserved

==============================================================


==============================================================

  IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT


   Before experimenting with the Netcom control, read the
   information below. 

   The Netcom control allows you to perform network operations
   that disrupt network communication with your PC. Resetting
   the network adapter or deleting names from the NetBIOS
   name table indiscriminantly will destroy communication
   between your PC and other workstations on the network.

==============================================================
   

                     Netcom Custom Control V1.2


The Netcom Custom Control implements NetBIOS general, session, and
datagram support. All common NetBIOS functions are supported.

This custom control can be used from C or C++ and is available 
from the Win 3.1 SDK Dialog Editor.

The only difference between the demo version of the control and
the commercial version is that the demo version displays a
dialog box that allows the user to register the control with
Northeast Data. There are no other functional differences.

Here are the overall capabilities:

   - Support for all standard NetBIOS emulations. This includes
     NetBIOS services running on LAN Manager, LAN Server, Novell,
     Banyan VINES, 3COM.

   - Support for multiple network adapters.

   - Multiple Netcom controls within the same application.

   - Interprocess communication between applications on the
     same workstation.

   - Communication between applications running on separate
     workstations.

   - Adapter status and reset.
   
   - NetBIOS name support.

   - NetBIOS session support.

   - NetBIOS datagram support.


=================
Legal Information
=================

The purchaser of the NetCom Control is allowed to use it and
distribute it in applications without paying any royalty, and without
printing or displaying a copyright notice for the control. This only
includes distribution of the NetCom Control DLL. It does not include
distribution of the header file, import library, or documentation that
comes with the NetCom Control. 

The purchaser of the NetCom Control may distribute the control DLL with
applications that are networked (multiple users accessing the DLL from
a file server) without paying any license fees to Northeast Data Corp.

The development files for using the NetCom Control (this excludes the
DLL) may only be used by the purchaser of the control. The purchaser
may install the development files on his/her own machine for development
purposes. These files may not be made available to any other person in
any way.

For use of the NetCom Control in any other fashion, the purchaser should
contact Northeast Data Corp. to make special arrangements. 



===================
The demo version   
===================

(does not apply if you have purchased a licensed version)

The demo version of the control will allow you to perform all functions
implemented by the commercial version. The only difference is that a
registration dialog box is displayed when the control is first loaded.

By registering the control with Northeast Data Corp., you get:

   - The commercial version of the control
   - A telephone and FAX number for support
   - A Compuserve ID for support
   - Free maintenance release updates
   - A discount on major releases
   - More information about using NetBIOS


===================
System Requirements
===================

You must have a NetBIOS application service running on your PC. This
requires a network adapter (etnernet, token ring, arcnet, etc.). This
service must be compatible with Microsoft Windows.

Microsoft Windows version 3.0 or higher.


===================
Installation
===================

Copy the NETCOM.DLL file to your Windows or Windows\System directory.

Before starting Windows, make sure you have loaded any network services
that are required for NetBIOS support.

Start Windows and run the test.exe program provided with the Netcom 
control.


===================
Programming
===================

The example file for the test.exe program are built using the Microsoft
NMAKE facility and the Microsoft C Compiler V8.0. You may need to make
modifications to the test.mak file and source code if you are using a
different compiler.

You will need to include the NETCOM.H file in your source code. Refer
to the contents of this file along with the following information:

Your application must create a NetCom window. This can be done by
using the SDK Dialog Editor and installing NETCOM.DLL as a custom
control. Create a dialog box for your application and place a NetCom
control on the dialog box. You can also place all other controls that
you want on the dialog.

Another way to use the control is to create a window in your application
using "NetCom" as the window class. This class gets registered by calling
the "RegisterNetCom" function as illustrated in the example program. 
This is only necessary if you implicitly link to the NetCom DLL. It is
not necessary if you use the LoadLibrary API function to load the DLL
explicitly.

All communication with the NetCom control is done by sending messages 
to its window handle. In addition to the standard Windows messages for
hiding and moving windows, these messages are provided:

   ---------------------------------------------------------------------
   Note: In the descriptions below, there are references to the "remote"
      workstation. If you are doing interprocess communication on your
      PC, "remote" refers to the other application on your PC. If you
      are communicating with a real remote workstation, "remote" refers
      to that workstation. 

      Since the Netcom control is re-entrant, you can actually perform
      inter-process communication within the control itself. In other
      words, you can send data to "yourself". It is perfectly OK to 
      have the Netcom control send data to and from itself or between
      Netcom controls in the same application. This has no value within
      the same application, other than allowing you to experiment with 
      the control.
   ---------------------------------------------------------------------


   NCM_SETCOMMAND

      Issues a command to the control. The command is specified in 
      wParam and is one of the following values. Unless stated otherwise,
      lParam is unused. The return value from this message is 0 for
      success, otherwise an error. The error codes are listed below.

      NCC_INIT

      Sets up the control for use by your application. This command
      must be executed before any other commands that perform network 
      operations are executed. The NetCom control will check for the
      presence of NetBIOS and will get the permanent name from the
      network adapter. If you pass the address of a string buffer in
      lParam, NetCom will place the permanent name into the buffer.
      You buffer needs to be at least 17 characters long.
   

      NCC_REGISTERNAME

      Registers the name that you have previously set up using the
      NCM_SETNAME message (see below). The name will be registered 
      as a NetBIOS UNIQUE name. The command fails if the name is 
      already registered by anyone on the network.


      NCC_REGISTERGROUP

      Registers the name that you have previously set up using the
      NCM_SETNAME message (see below). The name is registered as a 
      GROUP name. The command fails if the name is already registered 
      on your workstation, or if another workstation has registered the name
      as a unique name. Group names can be used to
      send data to multiple workstations.


      NCC_SENDDATAGRAM

      Sends the data you have previously set up using the NCM_SETDATA
      message (see below). The data is sent to the name you have set
      up using the NCM_SETREMOTENAME message (see below). The Remote Name
      can be set to a unique name or a group name. The datagram is sent 
      with the sender name you have set up using the NCM_SETNAME message.

      All workstations that have registered the remote name and have 
      posted a "Receive Datagram" will receive the data.Since this is a
      datagram, you receive no notification that other workstations
      have received the data.
                                                     

      NCC_RECEIVEDATAGRAM

      Sets up a "receive datagram" for the local name. You have to
      register a unique name or a group name before executing this 
      command. After executing this command, control will be returned 
      to your application. When a datagram is received, a 
      NCN_RECEIVEDDATAGRAM notification message will be sent to your 
      application.

      In order to receive another datagram after receiving one, you
      must issue this command again.


      NCC_CALL

      An attempt is made to establish a session with the workstation
      that has registered the name you have set up as a "Remote Name".
      The name of the caller (you) is the one you have set up as a
      local name.

      You have to register the NetName before executing this command. You
      do not have to register the RemoteName. Both names can be either
      unique or group names. Control is returned immediately to your
      application. When a connection is established with a remote workstation,
      your application will receive a notification message.


      NCC_LISTEN

      A listen is set up for the name you have set up as a Remote Name.
      This name must be a unique or group name that you have registered.
      You must also set up a local name that the remote workstation will
      use to call you.

      This command returns immediately to your application. When a remote
      workstation calls you, your application will receive a 
      NCN_NEWRECSESSION notification message with the number of the 
      "receive session" that has been established.

      You can use this notification to start a "receive" or a "send" to
      or from the remote station.


      NCC_SEND

      Data you have specified using the NCM_SETDATA message is sent to the
      remote workstation. Control is immediately returned to your
      application. When the remote workstation has received the data,
      the NCN_RECEIVEDDATA notification is sent to your application.

      You can use this notification to determine when to send the next block
      of data. The data is sent to the session number that was returned to
      you in the NCN_NEWSENDSESSION notification message. 


      NCC_RECEIVE
      
      A wait for data is set up for the session that was returned in the
      NCN_NEWRECSESSION notification message.

      Control is immediately returned to your application. When
      data is received, a NCN_RECEIVEDDATA notfication message is
      sent to your application.

      In order to receive more data from the sender, you must issue another
      NCC_RECEIVE command. This should be done immediately to prevent the 
      sender from timing out.


      NCC_HANGUPONREC

      Terminates the current RECEIVE SESSION. The remote workstation is 
      notified. You can no longer receive or send data on this session.


      NCC_HANGUPONSEND

      Terminates the current SEND session. The receiving workstation, 
      if any, is notified. You can no longer send or receive data on 
      this session.
      

      NCC_CANCELALL

      Cancels all network requests. This includes all commands for sending
      or receiving datagrams or data. It does not clear any registered
      names from the name table.


      NCC_RESET

      Cancels all network requests and clears all names from the name table.
      USE THIS COMMAND WITH CAUTION. If you are running on a network, this
      command will delete all names that other workstations may be using to
      communicate with your workstation. The adapter will be set to the
      same state is was when your workstation was initially booted (before
      any network applications were started).


      NCC_DELETENAME

      Deletes the current local name from the NetBIOS name table. 
      
      USE THIS COMMAND WITH CAUTION. 
      
      Network servers and applications register network names for 
      communication with your workstation. If you delete names that have 
      been registered by your network applications, these applications 
      will no longer be able to perform network operations. This command 
      deletes a group name or unique name, depending on the name specified 
      in the NetName property.


      NCC_RECEIVEANY

      Sets up a receive for any remote workstation attempting to send data
      to the current local name. This is different from the "Receive" 
      command, which only accepts data from a workstation that has 
      registered the name you have specified as your local name.

      Control is returned immediately to your application. When a remote
      workstation sends data, the NCM_RECEIVEDDATA notification message is
      sent to your application.


      NCC_RECEIVEANYFORANY

      This will set up a receive for any remote workstation sending data 
      to any session (rather than a specified session) on your workstation.


      NCC_ADAPTERSTATUS

      Displays a dialog box containing information about the adapter 
      indicated by the current Remote Name.

      If you specify "*" for the remote name, information from your own 
      adapter will be displayed. If you specify a unique or group name, 
      information from the first adapter that has registered the specified 
      name will be displayed.


      NCC_LISTNAMES

      A list of names in the name table for the adapter indicated by the
      current Remote Name is returned. If the Remote Name is "*", you 
      will get all the names registered on your workstation. If the
      remotename is set to a unique or group name, you will get the
      list of names registered by the first adapter on the network
      that has registered the specified name.

      You must supply a callback function in lParam. This function 
      must accept two argument - LPSTR and int. You should use the
      MakeProcInstance API function to get a pointer to your callback
      function (which needs to be exported). The NetCom control will
      call your callback function once for each name in the name table.
      Your function should return non-zero to continue - zero to stop
      the enumeration. 

      The first argument in your callback function will receive a
      null-terminated string that is the NetBIOS name that was found.
      The second argument is the name number.


      NCC_RECSESSSSTATUS

      Gets the session status for the current Receive Session number.
    
      Session status values are:

            1 - Listen pending
            2 - Call pending 
            3 - Session established
            4 - Hang Up pending
            5 - Hang Up complete   
            6 - Session aborted
   

      NCC_SENDSESSSTATUS

      Gets the session status for the current Send Session number.
    

            1 - Listen pending
            2 - Call pending 
            3 - Session established
            4 - Hang Up pending
            5 - Hang Up complete   
            6 - Session aborted
 

      NCC_RECEIVEBROADCAST

      Sets up a "Receive Datagram" for any workstation sending a broadcast
      datagram. Control returns immediately to your application. When a
      datagram is broadcasted by a remote workstation, the NCN_RECDATAGRAM
      notification message is sent to your application. You must then issue
      another NCC_RECEIVEBROADCAST command to receive anothere datagram.


      NCC_SENDBROADCAST
   
      Sends a datagram to all workstations on the network. You specify the
      data to send using the NCM_SETDATA message. All workstations that have
      posted a "Receive Broadcast Datagram" will receive the message. Since
      this is a datagram, your workstation will not be notified as to whether
      or not any workstations have received the message.


   NCM_SETNAME

      Sets the current local NetBIOS name. In order to use this name for
      most commands, you must issue the NCC_REGISTERNAME or NCC_REGISTERGROUP
      commands to register the name. You only have to register a name once -
      not each time you use it in a command. You specify the name as a
      pointer to a string in lParam. Specify the length in wParam. The
      maximum length of a name is 16 characters.


   NCM_SETREMOTENAME

      Sets the current Remote NetBIOS name. This name is used for various
      functions described above. You specify the remote name as a
      pointer to a string in lParam. Specify the length of the string
      in wParam. The maximum length of a name is 16 characters.


   NCM_SETSESSION

      If you specifiy 0 in wParam, the current RECEIVE session number
      is is set to the value you specify in lParam. 
      
      If you specify 1 in wParam, the current SEND session number
      is is set to the value you specify in lParam. 

      Session numbers are returned to you as the result of a CALL or
      LISTEN completion. When either of these complete, you get a
      NCN_NEWSENDSESSION or NCN_NEWRECSESSION notification.


   NCM_SENDDATA

      Sets the current data buffer to the buffer you point to in lParam.
      The length of the data is specified in wParam. The maximum data
      length is 128k minus 2 bytes for Send commands. The maximum length
      is 255 bytes for datagrams.
      
      This data is sent using the "SendDatagram", "SendBroadcast", or 
      "Send" commands.


   NCM_SETTRACE

      If wParam is set to TRUE, diagnostic messages are displayed for every
      network command performed. This is useful for troubleshooting
      your application. Setting wParam to FALSE disables display of
      diagnostic messages.



=====================
Notification Messages
=====================

These notifications are sent to the window that owns the NetCom Custom
Control window. The message is WM_COMMAND, with:

   wParam      - The ID of the NetCom control.
   lParam      - LOWORD - The notification message listed below.
                 HIWORD - Depends on the notification message - described
                          below.


   NCN_RECDATAGRAM

      HIWORD of lParam - A handle to a RECINFOSTRUCT as defined in
                         NETCOM.H.

   Sent when a datagram is received. You lock the handle contained in
   the high word of LPARAM and cast the result to a pointer to a 
   RECINFOSTRUCT. The structure members are:

      lpData   - Pointer to the received data
      nLen     - Length of the received data
      szFrom   - The NetBIOS name used by the sender of the datagram.


   NCN_NEWSENDSESSION

      HIWORD of lParam - The number of the new session.

   Sent when a new session has been established as a result of issuing
   the "Call" command. 


   NCN_NEWRECSESSION

      HIWORD of lParam - The number of the new session.

   Sent when a new session has been established as a result of issuing
   the "Listen" command.

   
   NCN_RECEIVE

      HIWORD of lParam - A handle to a RECINFOSTRUCT as defined in
                         NETCOM.H.

   Sent when data is received on a session. You lock the handle contained in
   the high word of LPARAM and cast the result to a pointer to a 
   RECINFOSTRUCT. The structure members are:

      lpData   - Pointer to the received data
      nLen     - Length of the received data
      szFrom   - The number of the session the data was received on
                  (as a string).


   NCN_SESSIONCLOSED

      HIWORD of lParam - The number of the session that has been closed.

   Sent when a session has been closed by the remote workstation.
   You can no longer issue sends or receives on this session. 


   NCN_SENDCOMPLETE

      HIWORD of lParam - The number of the session that the send has
                         completed on.

   A remote workstation has successfully received the data you sent
   in a "Send" command. This is the cue for you to send the next block
   of data to the remote workstation.



=============================
Error Codes
=============================
These are the error codes returned from messages sent to the NetCom
control. These constants are defined in NETCOM.H:

ERR_NONETBIOS       - NetBIOS not installed
ERR_ADDGROUP        - Failed to add a group name
ERR_ADDNAME         - Failed to add a unique name
ERR_SENDDATAGRAM    - Send datagram failed
ERR_SETUPRECEIVE    - Failed to set up a receive
ERR_NONAME          - Name not found in NetBIOS name table
ERR_NETINIT         - Failed to initialize the NetBIOS
ERR_DUPNAME         - Duplicate name
ERR_ADAPTERRESET    - Failed to reset adapter
ERR_HANGUP          - Failed to hang up session
ERR_CALL            - NetBIOS CALL failed
ERR_DELETENAME      - Failed to delete NetBIOS name
ERR_LISTEN          - Failed to set up a LISTEN
ERR_SEND            - Failed to send data
ERR_ADAPTERSTATUS   - Failed to get adapter status
ERR_MEMALLOC        - Memory allocation failure
ERR_SESSIONSTATUS   - Failed to get session status
ERR_SESSIONNOTFOUND - Session not found


=============================
General Notes
=============================

The NetCom control handles communication between your application and
the NetBIOS layer. Being object-oriented, it is more than simply an
interface layer. The control internally maintains information about
names, sessions, and data that have been specified by your application.

Your application uses the control to perform operations by first 
setting up appropriate information in the control, and then issuing a
command to the control to make it perform a NetBIOS operation.

The demo application uses most of the NetBIOS functions implemented in
the Netcom control. The TRACE property is set to TRUE in the demo, so
you will see many messages as commands are executed. Since many operations
are asynchronous, you will see messages that appear to be out of order.
For example, you may see a message indicating that a datagram has been
received - followed by a message indicating that the datagram has been
sent. This is normal behavior.


-------------------
The TRACE mode
-------------------
With the TRACE function in operation, you will see messages indicating
that operations are successful - possibly followed by messages indicating
that an operation has failed. This is because many NetBIOS commands are
performed in two steps - the first step being the submission of a request
to the NetBIOS driver. The driver acknowledges that it has received the
request (hence the "success" message). After the operation has been 
completed, NetBIOS notifies the Netcom control as to the final status of
the operation. This status may be "success" or "failure" and is reported
back to the application (and directly to the screen if the TRACE function
is active). You normally disable the TRACE function in your application
before distributing it.

-----------------------
Asynchronous Operations
-----------------------
Certain NetBIOS operations do not happen instantly. A request to add a
new name to the name table is time consuming (perhaps 5 seconds or more).
This request is handled synchronously by the Netcom control. It does not
return control to your application until the name has been added or the
attempt fails. 

The Netcom control has been designed with consideration for efficient 
operation of your workstation and ease of programming. There are 
"tradeoffs" between asynchronous vs. synchronous operations. 
Synchronous operations are easier for your application to deal with, but 
require suspending all execution in your application until the operation 
completes. Asynchronous operations allow your application to do other 
work while a request is being processed, but are more difficult for your 
application to work with - you have to handle the events that are sent 
to the Netcom control.

-------------------------------
Using the NetCom Control
-------------------------------
The first operation your application needs to do is to send the
"Initialize" command to the control. This lets it detect the NetBIOS
and set internal variables for use of the NetBIOS layer.

The next step is to set appropriate values for the network operations
you wish to perform. These are described above in the section on 
messages you can send to the control.

You do not have to do anything to shut down network operations. When
the NetCom window is destroyed, it automatically cancels all requests
that are outstanding (if any). This occurs when your application
terminates or you destroy the NetCom control window (or a window or
dialog box that contains it).

-------------
NetBIOS names
-------------
NetBIOS uses names to identify the sender and receiver of data sent
over the network (or within the same workstation). Names are also used
to locate network adapters.

There are two types of names: UNIQUE names, and GROUP names. Both are
exactly 16 characters long. The NetCom control automatically pads an name
you specify that is shorter than 16 characters WITH BLANKS. You should be
aware that IBM reserves the letters "IBM" for the first three characters
of any name, and the characters 0x00 through 0x1F (hex) for the 16th
character. You are free to use any other combination of characters. 

If you register a unique name, you are the only workstation on the network
that owns that name. Anyone else (including you) will encounter a NetBIOS 
error if they attempt to register this name. GROUP names are unique within
the same workstation, but can be registered by other workstations. Group
names are convenient for communication between several workstations. Any
names must be registered by you before you attempt to use the name as an
identification of your workstation to another workstation. 

The NetCom control keeps two names internally - a "Local Name" and a
"Remote Name". The local name is used for commands that require an 
identifier for the originator or receiver of a message. The remote name
is used as an identifier for the remote workstation you are communicating
with. The remote name is also used as an identifier for adapters in
commands that return information about network adapters. For your local
adapter, this name is always "*". Specifying a NetBIOS name will address
the adapter on the network that has registered that name.

You can add and delete NetBIOS names. Be aware that deleting a name that
is in use by another application on your workstation will disturb 
network communications.

A special NetBIOS name is the "Permanent Name". This is the set of
characters that is "burned in" to your network adapter. This name is
returned in the call to the initialization operation in the NetCom
control. You do not normally need to use the permanent name, which
is unique for all manufactured network adapters.


-----------------------
Datagrams
-----------------------
Datagrams are "one-way" communications. The sender sends the datagram to
all workstations that have registered the name specified by the senders
remote name. Any workstations that have register this names (unique or
group) and have established a "Receive Datagram" request will receive the
datagram. There is no way the sender can tell if any workstations actually
receive the datagram. This mechanism is commonly used to broadcast messages
to workstations (such as "Network being shut down").

-----------------------
Sessions
-----------------------
Sessions provide a means for guaranteed delivery of data between workstations.
To establish a session with another workstation, the sending workstation has
to register a NetBIOS name as a local name and post a "Call" for a 
a workstation against a name specified as a remote name (which does not
need to be registered by the listener).

The receiving workstation has to post a "Listen" for the name it has
specified as a remote name, which must match the local name registered by
the sender. The receiving workstation must also use a local name that 
matches the remote name specified by the sender.

It is important that the listen is set up on the receiving workstation
before the call is attempted on the sending workstation. Otherwise, the
session will not be established. 

It works kind of like a duplex "caller ID" - both workstations have to
accept each others names before a session will be established.

Once a session is set up (both parties receive an asynchronous notification
message, communication can take place. The notification message returns
a session number to each workstation (this number is not necessarily the
same on both workstations). The application uses this number thereafter to
refer to the session.

With the session in operation, either party can post a "Receive" or "Send"
command. Both of these are asynchronous (notification messages are sent to
the application to indicated completion). Completion of an operation is
an indication to set up another send or receive. 

The session is terminated when either party issues a "Hangup" command,
which also results in a notification message being sent to the application.

It is possible to have several sessions in operation concurrently. However,
it is up to the application to keep track of the session numbers. The
NetCom control only keeps track of two session numbers: the last one that
was established as a result of a "Listen", and the last one that was 
established as a result of a "Call". To manage multiple sessions, your
application has to set the session number in the NetCom control before
using the session.



=============================
Additional Information
=============================

For more information, consult:

   C Programmers Guide to NetBIOS, IPX, and SPX  by W. David Schwaderer,
   SAMS Publishing, a division of Prentice Hall Computer Publishing,
   11711 North College, Carmel, Indiana 46032, USA





   ================================================================

      Northeast Data Corp.
      2117 Buffalo Rd., Suite 290
      Rochester, NY  14624
      716-247-5934 (phone & FAX)

   ================================================================

   May 3, 1994

