AddConferenceName( ) and AddUserName( ) both invoke NetbiosAdd-Name( ) to add the requested conference and user names, respectively.
Unlike the previous NetBIOS Add Name routine, NetbiosAddName con-tains two formal parameter declarations, when the second parameter in-dicating whether the name is a group or unique name. If there is a problem adding any name, NetbiosAddName returns an illegal NcbNum (OOh), indicating there has been an error.
Participate( )
Participate( ) begins by displaying the requested user and conference names. It then invokes IssueReceiveDatagramRequests( ) which uses each Ncb in the InDgNcb array to issue a Receive Datagram request. Each Ncb in this array has its receive buffer in the corresponding InDg struc-ture array.
Participate( ) then calls EmitUserStatusMsg() and passes a parameter causing each existing participant within the selected conference to
re-Chapter 12: LAN Con!erencing 135
ceive notification that a new participant has joined the conference. Be-cause newly joining participants have previously issued conference Receive Datagrams, they receive the message as well (no conference lurk-ers here!).
Participate( ) calls SetUplnputLine( ) which clears display line 25 and initializes the program's keystroke-accumulation buffer. It then enters the primary program-processing loop which terminates only when the variable Participating becomes FALSE (when ESC is depressed by the user). Within this loop, the program constantly flips between processing received datagrams from the other conference participants and process-ing the keyboard.
When the user finally depresses the ESC key, the loop ends and Par-ticipate( ) calls EmitUserStatusMsg( ), passing a parameter causing each participant within the selected conference to receive notification that the user has departed the conference. Participate( ) spins on the transmis-sion of the departure message until it completes to avoid leaving a Send Datagram command pending after program termination.
ServiceDatagramNcbs( )
ServiceDatagramNcbs( ) checks the InDgNcb array to see if any Receive Datagram commands have completed. NetBIOS conveniently completes these Ncbs in the order they were used (IssueReceiveDatagramRe-quests( ) issued the Receive Datagrams using Ncb elements InDgNcb[O], InDgNcb[l], ... InDgNcb[MAX_NCBS]), so the routine needs only to check the first Ncb it discovered was not complete the last time it checked.
This InDgNcb array element-checking is all done modulo MAX _NCBS. The variable StartingNcb is defined as a static variable so that the current starting point is remembered between routine entries and the en-tire process is assisted by the TARGET _NCB preprocessor definition.
If an Ncb has completed, ServiceDatagramNcbs() invokes Process-ReceivedDatagram( ) to display the message. ServiceDatagramNcbs() then reuses the Ncb to issue another Receive Datagram command before checking the next Ncb for completion. This process continues until a pending Ncb is found, the StartingNcb variable is updated, and the rou-tine returns to Participate( ).
Note it is possible for all Ncbs to be completed at a given workstation when another conference workstation transmits a datagram. In this case, the datagram is not received by the lethargic workstation. The only
pos-136 Part II· Support Programming
sible solution is to increase the number ofNcbs in the InDgNcb array for that workstation. However, even this may not work because of restric-tions on the maximum number of outstanding commands, among other reasons.
In the final analysis, datagram communication works well in rela-tively light message-rate situations. Its flexibility comes at the price of data integrity problems in the general case.
ProcessReceivedDatagram( )
ProcessReceivedDatagram() checks the return code of the Ncb that re-quires processing. If the return code is not zero, Process Received-Datagram() returns without attempting to process the received datagram. Otherwise, ProcessReceivedDatagram() calls FetchCur-sorPosition( ) to save the current screen cursor position and scrolls the screen from line 1 (the second line) to line 24. It then displays the name of the user that transmitted the message and the user's message.
Before exiting, ProcessReceivedDatagram() calls SetPreviousCur-sorPosition( ) to restore the screen cursor to the position it had when ProcessReceivedDatagram( ) was entered.
ServiceKeyboard( )
ServiceKeyboard( ) checks to see if there have been any keystrokes since it was last invoked. If not, it exits. Otherwise, it reads the keystroke and examines it for significance:
• If a function key has been pressed or some other combination keystroke results in a BIOS extended keystroke (e.g., Alt-l), the keystroke is ignored. Note that this requires clearing the associ-ated second keystroke value with another keyboard read.
• If the backspace key was pressed, the last displayed keystroke character is erased and the accumulated keystroke buffer and buffer length are adjusted appropriately.
• If the ESC key was pressed, the Participating variable is set to FALSE.
• If the ENTER key was depressed, the accumulated keystrokes are sent as a message by calling SendKeyboardMsg( ).
Chapter 12: LAN Conjerencing 137
• Otherwise, the keystroke value is given to ApplyKeystroke( ) for processing (accumulation).
SendKeyboardMsg( )
SendKeyboardMsg( ) clears out the Send Datagram buffer area before copying the user name and message into the buffer. It then calls Netbios-SendDatagram( ) to send the conference datagram. Finally, before exit-ing, it calls SetUpInputLine() to initialize the program keystroke accumulation buffer.
Note that SendKeyboardMsg( ) does not check to see if the last Send Datagram command is still pending. Since all Send Datagram commands in this program use the same Ncb, this could be a serious program error.
However, NetbiosSendDatagram( ) does this at entry. In addition, Netbi-osSendDatagram( ) also uses other logic not used in previous discus-sions, so you may wish to examine it a bit closer than other functions.
ApplyKeystroke( )
ApplyKeystroke( ) first checks to see that the maximum number of key-strokes have not been accumulated. If they have, ApplyKeyStroke( ) beeps the workstation and returns. Otherwise, it checks to see that the character is a valid displayable ASCII character. If so, ApplyKeystroke( ) appends that keystroke to the accumulated ones and displays the charac-ter before returning.
Chapter 13