TipcSrvConnClose

Name

TipcSrvConnClose — close a connection to RTserver

Synopsis

T_BOOL TipcSrvConnClose(srv, conn_status) 
T_IPC_SRV srv; 
T_IPC_SRV_CONN_STATUS conn_status; 

Arguments

srv — connection to RTserver

conn_status — whether to keep a warm connection to RTserver (use T_IPC_SRV_CONN_WARM) or fully close the connection to RTserver (use T_IPC_SRV_CONN_NONE)

Return Values

TRUE if the connection to RTserver was successfully closed, FALSE otherwise.

Diagnostics

If TipcSrvConnClose fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcSrvConnClose closes the connection to RTserver. There are two ways to close the connection to RTserver:

If close_status is T_IPC_SRV_NONE, then TipcSrvConnClose removes all local subject information, destroys the connection, and finally calls the server destroy callbacks.

If close_status is T_IPC_SRV_CONN_WARM, then TipcSrvConnClose first closes the socket in the connection to RTserver. (As soon as the socket is closed, RTserver closes its own connection to RTclient.) TipcSrvConnClose then removes all buffered incoming messages from the connection read buffer and all buffered outgoing messages from the connection write buffer. All messages in the connection message queue are left in place, however. TipcSrvConnClose next calls TipcSrvConnGmdResend to resend any messages for GMD; this primes the warm connection with GMD messages so that sequence number order is preserved. The server close callbacks are then called.

Caution

An RTclient using the TCP/IP protocol to connect to RTserver may lose outgoing messages if the process terminates without calling TipcSrvConnClose. TCP/IP's SO_LINGER option, which preserves data, is ignored when closing a socket that has non-blocking I/O enabled. While data loss rarely occurs on UNIX and OpenVMS, it can happen very frequently on Windows. TipcSrvConnClose sets the block mode of the connection to TRUE before closing the connection's socket, which forces the operating system to deliver all flushed outgoing messages.

Messages that have been sent to RTserver but not flushed may be lost after a call to TipcSrvConnClose.

Use TipcSrvConnClose and T_IPC_SRV_NONE with caution from a connection callback such as a connection process callback. Because TipcSrvConnClose and T_IPC_SRV_NONE completely destroy the connection, the program crashes if control from the callback is returned to a function such as TipcSrvMainLoop.

See Also

TipcSrvConnOpen, TipcSrvConnGetConnStatus

Examples

This example opens a connection to RTserver, sends a message, and then fully closes the connection to RTserver with TipcSrvConnClose:

T_IPC_MT mt; 
 
/* Create a connection to RTserver. */ 
if (!TipcSrvConnOpen(srv, T_IPC_SRV_CONN_FULL)) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_NUMERIC_DATA); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
/* Send a message and make sure it gets flushed out. */ 
if (!TipcSrvConnMsgWrite(srv, "/system/admin", mt, TRUE, 
                         T_IPC_FT_STR, "speed_limit", 
                         T_IPC_FT_REAL8, 65.0, 
                         NULL)) { 
  return;  /* error */ 
}  
 
if (!TipcSrvConnFlush(srv)) { 
  return;  /* error */ 
}  
 
/* Fully close the connection to RTserver. */ 
if (!TipcSrvConnClose(srv, T_IPC_SRV_CONN_NONE)) { 
  return;  /* error */ 
}