TipcConnDestroy

Name

TipcConnDestroy — destroy a connection

Synopsis

T_BOOL TipcConnDestroy(conn) 
T_IPC_CONN conn; 

Arguments

conn — connection to destroy

Return Values

TRUE if connection was successfully destroyed, FALSE otherwise.

Diagnostics

If TipcConnDestroy fails, it returns FALSE and sets the global SmartSockets error number to:

Description

TipcConnDestroy destroys a connection. All memory for the connection is freed, and the connection’s socket is closed. All guaranteed message delivery files are closed, but the files on disk are not removed.

Caution

TipcConnDestroy does not try to flush the connection’s write buffer. Use TipcConnFlush before calling TipcConnDestroy to get this behavior.

TipcConnDestroy does not try to acknowledge any unacknowledged messages with a delivery mode of T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL that have been read from the connection. Use TipcMsgAck or TipcMsgDestroy before calling TipcConnDestroy to get this behavior.

Use TipcConnDestroy with caution from a connection callback such as a connection process callback. Because TipcConnDestroy completely destroys the connection, the program crashes if control from the callback is returned to a function such as TipcConnMainLoop.

A process with connections using the tcp protocol may lose outgoing messages if the process terminates without calling TipcConnDestroy to destroy each connection. 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. TipcConnDestroy sets the block mode of the connection to FALSE before closing the connection’s socket, which forces the operating system to deliver all flushed outgoing messages.

See Also

TipcConnCreate

Examples

TipcConnDestroy is useful when you use TipcConnAccept to accept a connection from a client, and then need to destroy the original connection (so that no more clients can connect):

/* create server side */ 
server_conn = TipcConnCreateServer("tcp:_node:4242"); 
if (server_conn == NULL) { 
  return;  /* error */ 
}  
 
/* wait for client */ 
client_conn = TipcConnAccept(server_conn); 
if (client_conn == NULL) { 
  return;  /* error */ 
}  
 
 /* destroy server connection */ 
if (!TipcConnDestroy(server_conn)) { 
  return;  /* error */ 
}