home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / mslang / netcom / readme.txt < prev   
Encoding:
Text File  |  1994-04-03  |  21.1 KB  |  578 lines
  1. ==============================================================
  2.  
  3.    Copyright 1994  Northeast Data Corp.  All Rights Reserved
  4.  
  5. ==============================================================
  6.  
  7.  
  8. ==============================================================
  9.  
  10.   IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
  11.  
  12.  
  13.    Before experimenting with the Netcom control, read the
  14.    information below. 
  15.  
  16.    The Netcom control allows you to perform network operations
  17.    that disrupt network communication with your PC. Resetting
  18.    the network adapter or deleting names from the NetBIOS
  19.    name table indiscriminantly will destroy communication
  20.    between your PC and other workstations on the network.
  21.  
  22. ==============================================================
  23.    
  24.  
  25.                      Netcom VBX V1.1d
  26.  
  27.  
  28. The Netcom VBX control implements NetBIOS general, session, and
  29. datagram support. All common NetBIOS functions are supported.
  30.  
  31. The control conforms to Visual Basic release 1.0, so it is
  32. compatible with Visual Basic versions 1.0, 2.0, 3.0 and higher,
  33. and with Visual C++ versions 1.0, 1.5 and higher.
  34.  
  35. This VBX control is also available from Northeast Data Corp.
  36. as a standard Windows "Custom Control". This is a DLL that
  37. can be used from C or C++ and is available from the Win 3.1
  38. SDK Dialog Editor.
  39.  
  40. The only difference between the demo version of the control and
  41. the commercial version is that the demo version displays a
  42. dialog box that allows the user to register the control with
  43. Northeast Data. There are no other functional differences.
  44.  
  45. Here are the overall capabilities:
  46.  
  47.    - Support for all standard NetBIOS emulations. This includes
  48.      NetBIOS services running on LAN Manager, LAN Server, Novell,
  49.      Banyan VINES, 3COM.
  50.  
  51.    - Support for multiple network adapters.
  52.  
  53.    - Multiple Netcom controls within the same application.
  54.  
  55.    - Interprocess communication between applications on the
  56.      same workstation.
  57.  
  58.    - Communication between applications running on separate
  59.      workstations.
  60.  
  61.    - Adapter status and reset.
  62.    
  63.    - NetBIOS name support.
  64.  
  65.    - NetBIOS session support.
  66.  
  67.    - NetBIOS datagram support.
  68.  
  69.  
  70. ===================
  71. The demo version
  72. ===================
  73.  
  74. The demo version of the control will allow you to perform all functions
  75. implemented by the commercial version. The only difference is that a
  76. registration dialog box is displayed when the control is first loaded.
  77.  
  78. By registering the control with Northeast Data Corp., you get:
  79.  
  80.    - The commercial version of the control
  81.    - A telephone and FAX number for support
  82.    - A Compuserve ID for support
  83.    - Free maintenance release updates
  84.    - A discount on major releases
  85.    - More information about using NetBIOS
  86.  
  87.  
  88. ===================
  89. System Requirements
  90. ===================
  91.  
  92. You must have a NetBIOS application service running on your PC. This
  93. requires a network adapter (etnernet, token ring, arcnet, etc.). This
  94. service must be compatible with Microsoft Windows.
  95.  
  96. Microsoft Windows version 3.0 or 3.1.
  97.  
  98.  
  99. ===================
  100. Installation
  101. ===================
  102.  
  103. Copy the NETCOM.VBX file to your Windows or Windows\System directory.
  104.  
  105. Before starting Windows, make sure you have loaded any network services
  106. that are required for NetBIOS support.
  107.  
  108. Start Windows and run Visual Basic or the PROJECT1.EXE program supplied
  109. with the Netcom control.
  110.  
  111. If you are running Visual Basic, you can load the PROJECT1.MAK file or
  112. load the Netcom control into your own project by using the "Add File"
  113. item under the FILE menu in Visual Basic.
  114.  
  115.  
  116. ===================
  117. Control Properties
  118. ===================
  119.  
  120. Note: In the descriptions below, there are references to the "remote"
  121.       workstation. If you are doing interprocess communication on your
  122.       PC, "remote" refers to the other application on your PC. If you
  123.       are communicating with a real remote workstation, "remote" refers
  124.       to that workstation. 
  125.  
  126.       Since the Netcom control is re-entrant, you can actually perform
  127.       inter-process communication within the control itself. In other
  128.       words, you can send data to "yourself". It is perfectly OK to 
  129.       have the Netcom control send data to and from itself or between
  130.       Netcom controls in the same application. This has no value within
  131.       the same application, other than allowing you to experiment with 
  132.       the control.
  133.  
  134. Adapter
  135.  
  136.       The network adapter number. If you have only one network adapter,
  137.       this number is always 0. You change this value to choose a different
  138.       adapter.
  139.  
  140. Command
  141.  
  142.    All of the following commands are executed on the adapter specified in
  143.    the "Adapter" property, which defaults to zero and is the correct value
  144.    if you only have one network adapter.
  145.  
  146.    For all commands, you should set up an error handler (using the On Error
  147.    VB statement). The error codes returned are documented in the NETCOM.H
  148.    file (the errors with the "VBERR_" prefix.
  149.  
  150.    1 - Initialize
  151.  
  152.       Sets up the control for use by your application. This command
  153.       must be executed before you perform any other commands and before
  154.       any properties that perform network operations are executed.
  155.    
  156.    2 - RegisterName
  157.  
  158.       Registers the name specified in the "NetName" property with
  159.       NetBIOS. The name is registered as a unique network name. The
  160.       command fails if the name is already registered by anyone on
  161.       the network.
  162.  
  163.    3 - RegisterGroup
  164.  
  165.       Registers the name specified in the "NetName" property with
  166.       NetBIOS. The name is registered as a group name. The
  167.       command fails if the name is already registered on your
  168.       workstation, or if another workstation has registered the name
  169.       as a unique name (see command #2). Group names can be used to
  170.       send data to multiple workstations.
  171.  
  172.    4 - SendDatagram
  173.  
  174.       Sends the data specified in the "SendData" property to the
  175.       name specified in the "RemoteName" property. The RemoteName
  176.       property can be set to a unique name or a group name. The
  177.       datagram is sent with the sender name specified in the "NetName"
  178.       property. This name must be registered (using command 2 or 3)
  179.       before sending the datagram. All workstations that have registered
  180.       the remote name and have posted a "Receive Datagram" will receive
  181.       the data you specify in the SendData property. Since this is a
  182.       datagram, you receive no notification that other workstations
  183.       have received the data.
  184.                                                      
  185.    5 - ReceiveDatagram
  186.  
  187.       Sets up a "receive datagram" for the name specified in the "NetName"
  188.       property. You have to register NetName as a unique name or a
  189.       group name before executing this command. After executing this
  190.       command, control will be returned to your application. When a
  191.       datagram is received, the Netcom "RecDatagram" procedure will
  192.       be called (see below, under "Events"). 
  193.  
  194.    6 - Call
  195.  
  196.       An attempt is made to establish a session with the workstation
  197.       that has registered the name specified in the "RemoteName" property.
  198.       The name of the caller (you) is specified in the "NetName" property.
  199.       You have to register the NetName before executing this command. You
  200.       do not have to register the RemoteName. Both names can be either
  201.       unique or group names. Control is returned immediately to your
  202.       application. When a connection is established with a remote workstation,
  203.       the "NewSendSession" routine is called in the Netcom control.
  204.  
  205.    7 - Listen
  206.  
  207.       A listen is set up for the name specified in the "RemoteName"
  208.       property. The remote workstation expects you to supply a valid
  209.       name in the "NetName" property. The NetName must be a unique or
  210.       group name that you have registered using commands 2 or 3. This
  211.       command returns immediately to your application. When a remote
  212.       workstation calls you, the "NewRecSession" routine in the NetCom
  213.       control is called. You can use this event to start sending or
  214.       receiving data to or from the remote workstation.
  215.  
  216.    8 - Send
  217.  
  218.       Data you have specified in the "SendData" property is sent to the
  219.       remote workstation. Control is immediately returned to your
  220.       application. When the remote workstation has received the data,
  221.       the "SendComplete" routine in the Netcom control is executed. You
  222.       can use this notification to determine when to send the next block
  223.       of data. The data is sent to the session specified in the "SendSession"
  224.       property. 
  225.  
  226.    9 - Receive
  227.       
  228.       A wait for data is set up for the session specified in the "RecSession"
  229.       property. Control is immediately returned to your application. When
  230.       data is received, the "RecData" routine in the Netcom control is called.
  231.       In order to receive more data from the sender, you must issue another
  232.       "Receive" command. This should be done immediately to prevent the sender
  233.       from timing out.
  234.  
  235.    10 - HangupReceive
  236.  
  237.       Terminates the session specified in the "RecSession" property. The
  238.       remote workstation is notified. You can no longer receive data on this
  239.       session.
  240.  
  241.    11 - HangupSend
  242.  
  243.       Terminates the session specified in the "SendSession" property. The
  244.       receiving workstation, if any, is notified. You can no longer send
  245.       data on this session.
  246.       
  247.    12 - CancelAll
  248.  
  249.       Cancels all network requests. This includes all commands for sending
  250.       or receiving datagrams or data. It does not clear any registered
  251.       names from the name table.
  252.  
  253.    13 - ResetAdapter
  254.  
  255.       Cancels all network requests and clears all names from the name table.
  256.       USE THIS COMMAND WITH CAUTION. If you are running on a network, this
  257.       command will delete all names that other workstations may be using to
  258.       communicate with your workstation. The adapter will be set to the
  259.       same state is was when your workstation was initially booted (before
  260.       any network applications were started).
  261.  
  262.    14 - DeleteName
  263.  
  264.       Deletes the name specified in the "NetName" property from the NetBIOS
  265.       name table. USE THIS COMMAND WITH CAUTION. Network servers and 
  266.       applications register network names for communication with your
  267.       workstation. If you delete names that have been registered by your
  268.       network applications, these applications will no longer be able to
  269.       perform network operations. This command deletes a group name or
  270.       unique name, depending on the name specified in the NetName property.
  271.  
  272.    15 - ReceiveAny
  273.  
  274.       Sets up a receive for any remote workstation attempting to send data
  275.       to the name you specify in the "NetName" property. This is different
  276.       from the "Receive" command, which only accepts data from a workstation
  277.       that has registered the name you specify in the "RemoteName" property.
  278.       Control is returned immediately to your application. When a remote
  279.       workstation sends data, the "RecData" routine in the Netcom control
  280.       is called.
  281.  
  282.       If you specify 255 in the "NameNumber" property, instead of setting
  283.       the "NetName" property, a "Receive-any-for-any" command is executed.
  284.       This will set up a receive for any remote workstation sending data
  285.       to any name (rather than a single name) on your workstation.
  286.  
  287.    16 - AdapterStatus
  288.  
  289.       Displays a dialog box containing information about the adapter you
  290.       specify in the "RemoteName" property. If you specify "*" in this
  291.       property, information from your own adapter will be displayed. If
  292.       you specify a unique or group name, information from the first adapter
  293.       that has registered the specified name will be displayed.
  294.  
  295.    17 - ListNames
  296.  
  297.       The "NetName" routine in the Netcom control is called for every
  298.       name in the NetBIOS name table for the adapter specified in the
  299.       "RemoteName" property. If the RemoteName property is "*", you 
  300.       will get all the names registered on your workstation. If the
  301.       remotename is set to a unique or group name, you will get the
  302.       list of names registered by the first adapter on the network
  303.       that has registered the specified name.
  304.  
  305.    18 - RecSessionStat
  306.  
  307.       Gets the session status for the session specified in the "RecSession"
  308.       property. This command is not very useful, since the only status ever
  309.       available is either 0 (failure) or 3 (session established). The other
  310.       statuses only occur in rare situations. The "SessionStatus" property
  311.       is set to the status of the receive session. Session status values are:
  312.  
  313.             1 - Listen pending
  314.             2 - Call pending 
  315.             3 - Session established
  316.             4 - Hang Up pending
  317.             5 - Hang Up complete   
  318.             6 - Session aborted
  319.    
  320.    19 - SendSessionStat
  321.  
  322.       Gets the session status for the session specified in the "SendSession"
  323.       property. This command is not very useful, since the only status ever
  324.       available is either 0 (failure) or 3 (session established). The other
  325.       statuses only occur in rare situations. The "SessionStatus" property
  326.       is set to the status of the send session. Session status values are:
  327.  
  328.             1 - Listen pending
  329.             2 - Call pending 
  330.             3 - Session established
  331.             4 - Hang Up pending
  332.             5 - Hang Up complete   
  333.             6 - Session aborted
  334.  
  335.  
  336.    20 - ReceiveBroadcast
  337.  
  338.       Sets up a "Receive Datagram" for any workstation sending a broadcast
  339.       datagram. Control returns immediately to your application. When a
  340.       datagram is broadcasted by a remote workstation, the RecDatagram
  341.       routine is called in the Netcom control. 
  342.  
  343.    21 - SendBroadcast
  344.    
  345.       Sends a datagram to all workstations on the network. You specify the
  346.       data to send in the "SendData" property. All workstations that have
  347.       posted a "Receive Broadcast Datagram" will receive the message. Since
  348.       this is a datagram, your workstation will not be notified as to whether
  349.       or not any workstations have received the message.
  350.  
  351.  
  352. DragIcon    
  353.  
  354.       A standard Visual Basic property.
  355.  
  356. DragMode
  357.  
  358.       A standard Visual Basic property.
  359.  
  360. Index
  361.  
  362.       A standard Visual Basic property.
  363.  
  364. Left
  365.       A standard Visual Basic property.
  366.  
  367. Name
  368.  
  369.       A standard Visual Basic property.
  370.  
  371. NameNumber
  372.  
  373.       The name number of the NetBIOS name specified in the "NetName"
  374.       property. You can override this value for sending broadcast
  375.       datagrams. This property is set automatically whenever you
  376.       change the NetName property. 
  377.  
  378. NetName
  379.  
  380.       The NetBIOS name for performing various network requests. This
  381.       can be a unique name or group name. You set this property and
  382.       then issue a "registerName" or "registerGroup" command to put
  383.       the name into the NetBIOS name table.
  384.  
  385. PermanentName
  386.  
  387.       Your adapter permanent node name. This is filled in automatically
  388.       when you issue the "Initialize" command.
  389.  
  390. RecSession
  391.  
  392.       The number of the network session returned from a "NetListen"
  393.       command.
  394.  
  395. RemoteName
  396.  
  397.       The NetBIOS remote name used for performing CALL, RECEIVE, and
  398.       SEND commands.
  399.  
  400. SendData
  401.  
  402.       Data to be sent as a datagram or to be sent to a remote workstation
  403.       using the "SendDatagram", "SendBroadcast", or "Send" commands.
  404.  
  405. SendSession
  406.  
  407.       The number of the network session returned from the "NetCall"
  408.       command.
  409.  
  410. SessionStatus
  411.  
  412.       The status from the "SendSessionStat" or "RecSessionStat" commands.
  413.       The values are:
  414.  
  415.  
  416.             0 - Unknown
  417.  
  418.             1 - Listen Pending
  419.  
  420.             2 - Call Pending
  421.  
  422.             3 - Session Established
  423.  
  424.             4 - Hangup Pending
  425.          
  426.             5 - Hangup Complete
  427.  
  428.             6 - Session Aborted
  429.  
  430. TabIndex
  431.  
  432.       A standard Visual Basic property.
  433.  
  434. TabStop
  435.  
  436.       A standard Visual Basic property.
  437.  
  438. Tag
  439.  
  440.       A standard Visual Basic property.
  441.  
  442. Top
  443.  
  444.       A standard Visual Basic property.
  445.  
  446. Trace
  447.  
  448.       If set to TRUE, diagnostic messages are displayed for every
  449.       network command performed. This is useful for troubleshooting
  450.       your application.
  451.  
  452. Visible
  453.  
  454.       A standard Visual Basic property.
  455.  
  456.  
  457.  
  458. ============
  459. Events
  460. ============
  461.  
  462. RecDatagram (Datagram as String,Sender as String)
  463.  
  464.    Called when a datagram is received. "Datagram" is the string that
  465.    was sent by the remote workstation. "Sender" is the name that the
  466.    remote workstation used as the sender of the datagram.
  467.  
  468. NewSendSession (Receiver as String,I as Integer)
  469.  
  470.    Called when a new session has been established as a result of issuing
  471.    the "Call" command. "Receiver" is the name that the responding workstation
  472.    used to connect with your workstation. "I" is the session number.
  473.  
  474. NewRecSession (Sender as String,I as Integer)
  475.  
  476.    Called when a new session has been established as a result of issuing
  477.    the "Listen" command. "Sender" is the name that the remote (sending)
  478.    workstation used to connect with your workstation. "I" is the session 
  479.    number.
  480.  
  481. NetName (S as String,I as Integer)
  482.  
  483.    Called repeatedly when a "ListNames" command is issued, for each name
  484.    found in the NetBIOS name table. S is the registered name. I is the
  485.    name number.
  486.  
  487. RecData (RecData as String,I as Integer)
  488.  
  489.    Called when data is received on a session. RecData is the data that
  490.    was received. I is the session number, which matches the session
  491.    number that was returned from the "Listen" command.
  492.  
  493.  
  494. SessionClosed (I as Integer)
  495.  
  496.    Called when a session has been closed by the remote workstation.
  497.    I is the number of the session. You can no longer issue sends or
  498.    receives on this session.   
  499.  
  500. SendComplete (I as Integer)
  501.  
  502.    A remote workstation has successfully recieved the data you sent
  503.    in a "Send" command. I is the session number.
  504.  
  505.  
  506. =============================
  507. General Notes
  508. =============================
  509.  
  510. The demo application uses most of the NetBIOS functions implemented in
  511. the Netcom control. The TRACE property is set to TRUE in the demo, so
  512. you will see many messages as commands are executed. Since many operations
  513. are asynchronous, you will see messages that appear to be out of order.
  514. For example, you may see a message indicating that a datagram has been
  515. received - followed by a message indicating that the datagram has been
  516. sent. This is normal behavior.
  517.  
  518. With the TRACE function in operation, you will see messages indicating
  519. that operations are successful - possibly followed by messages indicating
  520. that an operation has failed. This is because many NetBIOS commands are
  521. performed in two steps - the first step being the submission of a request
  522. to the NetBIOS driver. The driver acknowledges that it has received the
  523. request (hence the "success" message). After the operation has been 
  524. completed, NetBIOS notifies the Netcom control as to the final status of
  525. the operation. This status may be "success" or "failure" and is reported
  526. back to the application (and directly to the screen if the TRACE function
  527. is active).
  528.  
  529. Certain NetBIOS operations do not happen instantly. A request to add a
  530. new name to the name table is time consuming (perhaps 5 seconds or more).
  531. This request is handled synchronously by the Netcom control. It does not
  532. return control to your application until the name has been added or the
  533. attempt fails. 
  534.  
  535. The Netcom control has been designed with consideration efficient operation
  536. of your workstation and ease of programming. There are "tradeoffs" between
  537. asynchronous vs. synchronous operations. Synchronous operations are easier
  538. for your application to deal with, but require suspending all execution
  539. in your application until the operation completes. Asynchronous operations
  540. allow your application to do other work while a request is being processed,
  541. but are more difficult for your application to work with - you have to
  542. handle the events that are sent to the Netcom control.
  543.  
  544. It is possible to do both sends and receives on the same session, even
  545. though you initiated the session via a Call or Listen. Completion of a
  546. "Call" fills in the "Sendsession" property. Completion of a "Listen" fills
  547. in the "RecSession" property. If you perform a "Listen" and then want to
  548. do a "Send", copy the "RecSession" value into the "SendSession" property
  549. and then issue the "Send" command. Do the reverse for performing a "Receive"
  550. on a session that was established by issuing a "Call" command.
  551.  
  552. =============================
  553. Additional Information
  554. =============================
  555.  
  556. Much of the information above assumes knowledge of NetBIOS. For more
  557. information, consult:
  558.  
  559.    C Programmers Guide to NetBIOS, IPX, and SPX  by W. David Schwaderer,
  560.    SAMS Publishing, a division of Prentice Hall Computer Publishing,
  561.    11711 North College, Carmel, Indiana 46032, USA
  562.  
  563.  
  564.  
  565.  
  566.  
  567.    ================================================================
  568.  
  569.       Northeast Data Corp.
  570.       2117 Buffalo Rd., Suite 290
  571.       Rochester, NY  14624
  572.       716-247-5934 (phone & FAX)
  573.  
  574.    ================================================================
  575.  
  576.    April 3, 1994
  577.  
  578.