Notification record

The notification record is used to provide event information. You receive this information by using the GetNextNote call. If it is a variant record, the number of fields depends on the type of notification. See Figure 1 for the Pascal declaration of this record.

Figure 1. Notification record

   NotificationInfoType =
        record
        Connection: ConnectionType;
        Protocol: ProtocolType;
        case NotificationTag: NotificationEnumType of
             BUFFERspaceAVAILABLE:
                 (
                 AmountOfSpaceInBytes: integer
                 );
             CONNECTIONstateCHANGED:
                 (
                 NewState: ConnectionStateType;
                 Reason: CallReturnCodeType
                 );
             DATAdelivered:
                 (
                 BytesDelivered: integer;
                 LastUrgentByte: integer;
                 PushFlag: Boolean
                 );

             FSENDresponse:
                 (
                 SendTurnCode: CallReturnCodeType;
                 SendRequestErr: Boolean;
                 );
             PINGresponse:
                 (
                 PingTurnCode: CallReturnCodeType;
                 ElapsedTime: TimeStampType
                 );
             RAWIPpacketsDELIVERED:
                 (
                 RawIpDataLength: integer;
                 RawIpFullLength: integer;
                 );
             RAWIPspaceAVAILABLE:
                 (
                 RawIpSpaceInBytes: integer;
                 );
             SMSGreceived: ();
             TIMERexpired:
                 (
                 Datum: integer;
                 AssociatedTimer: TimerPointerType
                 );
             UDPdatagramDELIVERED:
                 (
                 DataLength: integer;
                 ForeignSocket: SocketType;
                 FullLength: integer
                 );
             UDPdatagramSPACEavailable: ();
             URGENTpending:
                 (
                 BytesToRead: integer;
                 UrgentSpan: integer
                 );
             USERdefinedNOTIFICATION:
                 (
                 UserData: UserNotificationDataType
                 );
             end;

Connection

The client’s connection number to which the notification applies. In the case of USERdefinedNOTIFICATION, this field is as supplied by the user in the AddUserNote call.

Protocol

In the case of USERdefinedNOTIFICATION, this field is as supplied by the user in the AddUserNote call. For all other notifications, this field is reserved.

NotificationTag

The type of notification being sent. A set of fields depends on the value of the tag. Possible tag values relevant to the TCP/UDP/IP interface and the corresponding fields are:

BUFFERspaceAVAILABLE

Notification given when space becomes available on a connection for which TcpSend previously returned NObufferSPACE.

AmountOfSpaceInBytes: The minimum number of bytes that the TCP/IP service has available for buffer space for this connection. The actual amount of buffer space might be more than this number.

CONNECTIONstateCHANGED

Indicates that a TCP connection has changed state.

NewState: The new state for this connection.
Reason: The reason for the state change. This field is meaningful only if the NewState field has a value of NONEXISTENT.

Notes:

The following lists show the sequence of state notifications for a connection.
- For active open:
  - OPEN
  - RECEIVINGonly or SENDINGonly
  - CONNECTIONclosing
  - NONEXISTENT
- For passive open:
  - OPEN
  - RECEIVINGonly or SENDINGonly
  - CONNECTIONclosing
  - NONEXISTENT
Your program should be prepared for any intermediate step or steps to be skipped.
The normal TCP connection closing sequence can lead to a connection staying in CONNECTIONclosing state for up to two minutes, corresponding to the TCP state TIME-WAIT.
Reason codes giving the reason for a connection changing to NONEXISTENT are:
- OK
- UNREACHABLEnetwork
- TIMEOUTopen
- OPENrejected
- REMOTEreset
- WRONGsecORprc
- FATALerror
- TCPipSHUTDOWN

DATAdelivered

Notification given when your buffer (named in an earlier TcpReceive or TcpFReceive request) contains data.

Note: The data delivered should be treated as part of a byte stream, not as a message. There is no guarantee that the data sent in one TcpSend (or equivalent) call on the foreign host is delivered in a single DATAdelivered notification, even if the PushFlag is set.

BytesDelivered: Number of bytes of data delivered to you.
LastUrgentByte: Number of bytes of urgent data remaining, including data just delivered.
PushFlag: TRUE if the last byte of data was received with the push bit set.

FSENDresponse

Notification given when a TcpFSend request is completed, successfully or unsuccessfully.

SendTurnCode: The status of the send operation.

PINGresponse

Notification given when a PINGresponse is received.

PingTurnCode: The status of the PING operation.
ElapsedTime: The time elapsed between the sending of a request and the reception of a response. This field is valid only if PingTurnCode has a value of OK.

RAWIPpacketsDELIVERED

Notification given when your buffer (indicated in an earlier RawIpReceive request) contains a datagram. Only one datagram is delivered on each notification. Your buffer contains the entire IP header, plus as much of the datagram as fits in your buffer.

RawIpDataLength: The actual data length delivered to your buffer. If this is less than RawIpFullLength, the datagram was truncated.
RawIpFullLength: Length of the packet, from the TotalLength field of the IP header.

RAWIPspaceAVAILABLE

When space becomes available after a client does a RawIpSend and receives a NObufferSPACE return code, the client receives this notification to indicate that space is now available.

RawIpSpaceInBytes: The amount of space available always equals the maximum size IP datagram.

RESOURCESavailable

Notice given when resources needed for a TcpOpen or TcpWaitOpen are available. This notification is sent only if a previous TcpOpen or TcpWaitOpen returned ZEROresources.

SMSGreceived

Notification given when one or more special messages (Smsgs) arrive. The GetSmsg call is used to retrieve queued Smsgs.

TIMERexpired

Notification given when a timer set through SetTimer expires.

Datum: The data specified when SetTimer was called.
AssociatedTimer: The address of the timer that expired.

UDPdatagramDELIVERED

Notification given when your buffer, indicated in an earlier UdpNReceive or UdpReceive request, contains a datagram. Your buffer contains the datagram excluding the UDP header.

Note: If UdpReceive was used, your buffer contains the entire datagram excluding the header, with the length indicated by DataLength. If UdpNReceive was used, and DataLength is less than FullLength, your buffer contains a truncated datagram. The reason is that your buffer was too small to contain the entire datagram.

DataLength: Length of the data delivered to your buffer.
ForeignSocket: The source of the datagram.
FullLength: The length of the entire datagram, excluding the UDP header. This field is set only if UdpNReceive was used.

UDPdatagramSPACEavailable

Notification given when buffer space becomes available for a datagram for which UdpSend previously returned NObufferSPACE because of insufficient resources.

URGENTpending

Notification given when there is urgent data pending on a TCP connection.

BytesToRead: The number of incoming bytes not yet delivered to the client.
UrgentSpan: Number of bytes that are not delivered to the last known urgent pointer. No urgent data is pending if this is negative.

USERdefinedNOTIFICATION

Notice generated from data passed to AddUserNote by your program.

UserData: A 40-byte field supplied by your program through AddUserNote. Connection and protocol fields also are set from the values supplied to AddUserNote.