Release Notes - Socket Tools Library

You might also be interested in the release notes for the libraries that this one is built on:

• Admin
• C++ Tools (this was a separate library prior to version 6.0 at which point it was merged with the Win32 Tools Library
• Win32 Tools
• IO Tools

Version 6.1

• Breaking Change we now allow exceptions to propagate out of JetByteTools::Socket::CConnectionMaintainingStreamSocketConnectionFilter::CancelConnectionRetries() rather than catching them in a catch(...) handler.
• The constructors for JetByteTools::Socket::CDatagramSocketAllocator now default the spin count argument to 0 thus making it optional, previously it was required.
• Changed JetByteTools::Socket::IAllocatePoolableSockets::ReleaseSockets() so that it returns a bool. The function now returns true if there were sockets present when the allocator was flushed.
• Added JetByteTools::Socket::INamedServerShutdownCallback and JetByteTools::Socket::IServerShutdownCallback which can be passed to instances of JetByteTools::Socket::CNamedServerCollection or JetByteTools::Socket::CServerCollection respectively and which are used to call back to tell you as each server in the collection is shutdown. This is especially useful if you are shutting down a collection of servers from within a Windows service as you can notify the service control manager of your progress as each server is shutdown rather than having to guess and hope for the best that the timeout that you have specified is enough to shutdown an unknown number of servers in your collection. Note that null objects that implement each of these interfaces exist in the form of JetByteTools::Socket::CNullNamedServerShutdownCallback and JetByteTools::Socket::CNullServerShutdownCallback should you need them.
• Added static versions of JetByteTools::Socket::CSocket::GetLocalAddress() and JetByteTools::Socket::CSocket::GetRemoteAddress() which return the addresses for the supplied socket.
• Added the ability to specify to an instance of JetByteTools::Socket::CSocketAllocator that you don't want it to pool sockets at all.
• Added a configuration option, JETBYTE_TRACK_SOCKET_REFERENCES which when defined as 1 causes code to be inserted that tracks the reference counting that occurs on instances of all socket classes derived from JetByteTools::Socket::TAsyncSocket. If a socket is over released (i.e. release is called on a socket where the reference count is currently zero) then a trace of all calls to JetByteTools::Socket::TAsyncSocket<T>::AddRef() and JetByteTools::Socket::TAsyncSocket<T>::Release() will be printed to the debug trace output. If a socket is destroyed and the reference count is not zero then a trace is also printed. Note that there is a considerable run-time cost for this functionality but it is non invasive and no external code changes are needed. See here http://www.lenholgate.com/archives/000867.html for more details.
• Added JetByteTools::Socket::CSocketReferenceTracker which is used to implement the reference tracking code that is detailed above.
• Added an exception handler to JetByteTools::Socket::CStreamSocketConnectionManager::FilterConnectionEstablished() which will report the error and abort the connection on the socket in question should an exception escape from either JetByteTools::Socket::IFilterStreamSocketConnections::FilterConnectionEstablished() or JetByteTools::Socket::IStreamSocketConnectionManagerCallback::OnConnectionEstablished().
• Fixed a race condition bug in JetByteTools::Socket::CStreamSocketServerEx whereby code waiting for the server to shutdown would complete its wait before the server had completely finished with the last buffer that was in use when the final socket was closed. This could, potentially, have resulted in a race condition between the cleanup and destruction of the buffer allocator that was being used and the final release of the buffer that was used in the final socket's final operation. It's very unlikely that you'd see this in production code, but it was causing a test to fail.

Version 6.0

• Changes due to the merging of C++Tools and RegistryTools with Win32Tools.
• Changes to how we share critical sections amongst sockets to take advantage of the JetByteTools::Win32::ICriticalSectionFactory changes.
  • Moved JetByteTools::Socket::IFilterableStreamSocket::GetLock() to JetByteTools::Socket::IStreamSocket
  • JetByteTools::Socket::CSocketAllocator and JetByteTools::Socket::TSocketAllocator now take a pointer to an optional instance of JetByteTools::Win32::ICriticalSectionFactory. If this instance is non null then the version of JetByteTools::Socket::CSocketAllocator::CreateSocket() that takes an instance of JetByteTools::Win32::ISharedCriticalSection is used for socket creation. If no lock factory is supplied then the version of JetByteTools::Socket::CSocketAllocator::CreateSocket() that only takes the number of user data slots required is used. Derived classes must provide implementations of both versions of CreateSocket() but can fail one or the other if they wish as long as their constructors ensure that either a lock factory is always passed through to the JetByteTools::Socket::CSocketAllocator base class or that one never is. Derived classes can use the new version of the CreateSocket() method to provide sockets that have their own unique lock and which can not ever share locks.
  • JetByteTools::Socket::CStreamSocket and JetByteTools::Socket::TAsyncSocket now take an instance of JetByteTools::Win32::ICriticalSection rather than an instance of JetByteTools::Win32::ICriticalSectionFactory in their constructors.
  • Added two new versions of all socket classes; e.g. JetByteTools::Socket::CUniqueLockStreamSocket and JetByteTools::Socket::CSharedLockStreamSocket. These are now the concrete socket classes which are allocated by the allocators. The unique lock versions have an instance of a JetByteTools::Win32::CCriticalSection inside them, the shared lock versions use a JetByteTools::Win32::CSmartSharedCriticalSection to manage their shared lock. This allows allocators to allocate either using a lock factory or using unique locks. Note that not using JetByteTools::Win32::CUniqueCriticalSectionFactory to provide unique (but conceptually shared) locks gives a space advantage as shared locks are larger than non shared locks. However, JetByteTools::Win32::CUniqueCriticalSectionFactory CAN be used to swap the lock allocation policy at run time rather than compile time...
• Bug fix in SocketTools\WinsockWrapper.h for compilers earlier than VS2005 compiling with Platform SDK 6.1; we now use JETBYTE_MESSAGE to output the warning message.
• Bug fix and subsequent changes to various JetByteTools::Socket::CSocket methods so that we report the correct 'last error' when errors occur.
• Bug fix in JetByteTools::Socket::CAddressIPv6, we were failing to parse IPv6 address strings correctly, we now correctly parse [ffff:ffff:ffff:ffff:ffff]:port style address strings. This will have had a knock on effect with JetByteTools::Socket::CFullAddress also failing to parse these address strings correctly.
• JetByteTools::Socket::IAsyncSocket::TryRead() is no longer 'nothrow' as it CAN thrown an exception if the buffer that it is supplied has no space left in it.
• Breaking Change Moved JetByteTools::Socket::CSmartBuffer to the IOTools library, the header is now in the IOTools library and the class is now JetByteTools::IO::CSmartBuffer.
• Breaking Change JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter::IProcessBufferList::OnListFull() now takes a socket reference. This allows you to close the connection if you need to.
• Added JetByteTools::Socket::CSocket::TryBind() which attempts to bind and returns an error code on failure.
• All socket allocators that do not require a lock factory now take an optional spinCount which is used to initialise the critical sections used by the sockets that it creates.
• Changes to how JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter works. All of the policy decisions regarding what to do when the buffer list fills up has now been passed on to an instance of the JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter::IProcessBufferList interface, so you always need to supply one of these now. There's a new class JetByteTools::Socket::CFlowControlListProcessor which provides the old functionality of 'throw away earliest', and 'throw away latest' and also includes the option to abort the connection if too much data is being buffered. JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter also handles write completion errors now, it used to pretend to but didn't. JetByteTools::Socket::IMonitorStreamSocketFlowControl has a new function which is called when a write completion error occurs and you can do something about it, if you can(!) and then return either true or false depending on if you want the failure to cause more data to be sent from the queued data or not.

Version 5.2.5

• Fixed a bug in the dispatch of JetByteTools::Socket::IStreamSocketCallback::OnConnectionClosed() from within JetByteTools::Socket::CStreamSocket::OnFinalRelease(). We now ensure that the socket's reference count is valid before calling the callback method.
• Fixed a bug in the suppression of the WSAENOTSOCK error in JetByteTools::Socket::TAsyncSocket::Shutdown() when we know the socket isn't valid at the point where we call shutdown.

Version 5.2.4

• We now compile with /Wall (in VS2005 and later) to enable all warnings, even those that are disabled by default.
• Removed (no, really, we did this time) the ConnectionErrorSource.h header file.
• Removed JetByteTools::Socket::IStreamSocketCallback::OnError(), the one that had a socket and a message for arguments. We now deal with errors a little better...
• Added a version of JetByteTools::Socket::IServerControl::WaitForShutdownToComplete() that takes a timeout value and returns a bool to say if the server shut down within the timeout. This makes it easier to deal with servers that have hung for one reason or another. They now don't have to stop the entire process from shutting down.
• Added JetByteTools::Socket::IServerControl::ForceShutdown() which causes a server to shut down even if it would normally wait. Use with care.
• JetByteTools::Socket::CStreamSocket::OnFinalRelease() is now nothrow().
• JetByteTools::Socket::TAsyncSocket::TryRead(), etc are all now nothrow().
• Added JetByteTools::Socket::CStreamSocketConnectionCollection, JetByteTools::Socket::CStreamSocketBroadcastableConnectionCollection and JetByteTools::Socket::CStreamSocketNamedConnectionCollection as people seem to find it hard to write 'chat server' style servers where one connection needs to interact with others. There will eventually be example servers that use these.
• It's now possible to write a connection filter that filters OnClientClose(), OnConnectionReset() and OnClosed() events.
• We now support two styles of "zero byte read", sync and async.
• Added JetByteTools::Socket::CSocketAllocator::LockUserDataSlots() as required by the change to JetByteTools::Win32::IProvideUserData.
• JetByteTools::Socket::TAsycnSocket::TryRead() and JetByteTools::Socket::TAsycnSocket::TryWrite() are now nothrow.

Version 5.2.3

• Some whitespace changes to remove incorrect tabs.
• Removed The ConnectionErrorSource.h header file and the whole concept that the enum represented. This has also led to the removal of the various OnConnectionError() callbacks as these errors are now handled by more appropriate callbacks.
• Changed how some callbacks are dispatched to user code. See here for more details.
• Make use of JetByteTools::IO::IBuffer::GetWSABUFCount() so that we can work with buffers that provide multiple WSABUF structures. Note that there aren't actually any buffers in the library that do this yet.
• Added a new example server and client which demonstrate various methods of terminating a socket connection.
• JetByteTools::Socket::CReadSequencingStreamSocketConnectionFilter now takes an instance of JetByteTools::Socket::IAllocateSequencedStreamSockets rather than JetByteTools::Socket::IAllocateStreamSockets. It actually only requires the opaque user data part of the interface but this change makes it clearer that the filter only works with sequenced sockets...
• Some changes to WinsockWrapper.h for when JETBYTE_PLATFORM_SDK_VERSION == 0x0610 and we're building with anything earlier than VS2005 as version 6.1 of the Platform SDK defines a 'clever' template version of _WSPIAPI_COUNTOF from WSPIAPI.H and the earlier compilers can't deal with...
• Fixed JetByteTools::Socket::CAddressRenderer so that it always passes NI_NUMERICSERV to JetByteTools::Socket::CNameInfo as otherwise you get a WSANO_DATA error on some Windows platforms if the port isn't a "well known" port.

Version 5.2.2

• Some changes to WinsockWrapper.h for when JETBYTE_PLATFORM_SDK_VERSION == 0x0610 as version 6.1 of the Platform SDK does not define a SOCKADDR_STORAGE typedef for Windows versions of less than 0x0501. We warn about this and include our own typedef if this is the case.
• Changes to JetByteTools::Socket::CAddressIPv6() and JetByteTools::Socket::CAddressTypeIPv6() so that we don't need the constant in6addr_any to exist, it's zero and it's not present when building for some versions of Windows.
• Fixed JetByteTools::Socket::CAddressRenderer so that it actually uses the includePortOrService flag that's passed in.
• Added JetByteTools::Socket::IMaintainStreamSocketConnections and JetByteTools::Socket::CConnectionMaintainingStreamSocketConnectionFilter which enable connections to be automatically reconnected if they are dropped.
• Added JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter which monitors the amount of data that has been sent and limits the amount of data that can be 'pending a write completion' by buffering data in its own buffers and sending from them as writes complete.
• Added JetByteTools::Socket::IMonitroStreamSocketFlowControl which allows you to monitor how a class like JetByteTools::Socket::CFlowControlStreamSocketConnectionFilter is working.
• Added JetByteTools::Socket::IAcceptStreamSocketConnectionFilters which makes it easier to add connection filters to servers and connection managers.
• Moved the data sequencing functions from JetByteTools::Socket::IStreamSocketEx to JetByteTools::Socket::IFilterableStreamSocket to allow connection filters to control the sequencing of data if they require.
• Changed how connection shutdown and closure works. See here: http://www.lenholgate.com/archives/000779.html for more details.
• Fixed JetByteTools::Socket::CDatagramSocketServer so that it continues to post read requests when it gets ERROR_PORT_UNREACHABLE errors. A port unreachable error from a send results in a pending recv completing with ERROR_PORT_UNREACHABLE and we only issued a new recv if the completion is without error which would lead to read starvation and eventually to a server that wouldn't receive any more datagrams.
• Added JetByteTools::Socket::IStreamSocketConnectionManager::OnSocketCreated(), JetByteTools::Socket::IDatagramSocketConnectionManagerCallback::OnSocketCreated() and JetByteTools::Socket::IDatagramServerSocketConnectionManager::OnSocketCreated() which are called after new sockets are created and which is passed the raw SOCKET. You can use these to set the socket up in any way you want to, such as set various socket options that the framework doesn't have any explicit support for, or whatever.
• Changed JetByteTools::Socket::IFilterStreamSocketConnections::FilterConnect() so that it takes an instance of JetByteTools::Socket::IFullAddress rather than just JetByteTools::Socket::IAddress and so that it also gets to filter the user data.
• Added JetByteTools::Socket::IFilterStreamSocketConnections::FilterConnectionFailed() which allows filters to be notified of failures to establish connections.
• Added support to JetByteTools::Socket::ICreateStreamSocketConnections for setting a socket's send and recv buffer sizes before establishing the connection.
• Added support to JetByteTools::Win32::CStreamSocketServer, JetByteTools::Win32::CStreamSocketServerEx and JetByteTools::Win32::CStreamSocketConnectionManager for specifying the send and recv buffer sizes of all sockets created.
• Added JetByteTools::Socket::ICreateStreamSocketConnections::AsyncConnectNoThrow(), JetByteTools::Socket::ICreateStreamSocketConnections::ConnectAsyncIfAvailable() and JetByteTools::Socket::ICreateStreamSocketConnections::ConnectAsyncIfAvailableNoThrow().
• Changed JetByteTools::Socket::CReadSequencingStreamSocketConnectionFilter and JetByteTools::Socket::CReadTimeoutStreamSocketConnectionFilter to use JetByteTools::Socket::IAcceptStreamSocketConnectionFilters to register themselves.
• Fixed a memory leak in JetByteTools::Socket::CSequencedStreamSocket::SequenceData where we were calling delete when we should have been calling delete [].

Version 5.2.1

• VS 2008 support - Adding projects and solutions and excluding warning 4627...
• This is the first release built using continuous integration, some project file fixes to fix incorrect output directories, etc so that x64 and x86 builds can be done in complete isolation.
• A hacky fix in IServerControl.h to work around the InitiateShutdown macros that have been moved in a recent version of the Platform SDK. See the comment in the header for details.
• In NameInfo.cpp, if _WIN32_WINNT < 0x0502 then use getnameinfo() as GetNameInfoW() isn't available on this platform.

Version 5.2

• Documented all of the example servers: here
• x64 port - Some data types have changed.
• Some tightening up on const.
• IPv6 support - the code has now actually been tested on a machine with IPv6 installed on it...
• Added JetByteTools::Socket::CFullAddress, because we didn't already have enough address related classes... This class can fabricate all of the bits of addressing information that aren't actually present in a SOCKADDR structure and provide an implementation of JetByteTools::Socket::IFullAddress. It can also use its powers of guestimation to construct itself from string representations of addresses in either IPv4, dotted ip "xxx.xxx.xxx.xxx:port" format or IPv6 "[ffff:ffff:ffff:ffff:ffff]:port" format.
• Added JetByteTools::Socket::IIPAddress which is where the typedef for a port and the access method to get at it now lives.
• Added ListenBacklog.h and SequenceId.h since these are now types.
• Added JetByteTools::Socket::CNameInfo to perform address to name translations for any address family. This replaces using inetaddr() etc. and works with IPv6 as well as IPv4.
• You can now construct an instance of JetByteTools::Socket::CAddress from a string representation of an IPv4 or IPv6 address.
• You can now construct an instance of JetByteTools::Socket::CAddressIPv6 from a string representation of an IPv6 address.
• Both JetByteTools::Socket::CAddressTypeIPv4 and JetByteTools::Socket::CAddressTypeIPv6 now provide a static instance of the class which is probably all you'll ever need.
• JetByteTools::Socket::CDatagramSocketConnectionManager now keeps a track of active connections and the shutdown procedure waits for them all to terminate.
• Breaking Change JetByteTools::Socket::CStreamSocket::RequestWrite() no longer splits data that is too big for a single buffer across multiple buffers, it throws an exception instead. You need to use JetByteTools::Socket::CSequencedStreamSocket if you require that functionality as the process of splitting a single logical write across multiple physical writes requires that the socket supports sequencing.
• JetByteTools::Socket::TAsyncSocket now provides an OnDetach() function which is called when a socket is being returned to the socket allocator after use. This can be used to clean up any per connection resources that are no longer required. See JetByteTools::Socket::CSequencedStreamSocket::OnDetach() for example usage.
• JetByteTools::Socket::IStreamSocket now provides Get/Set functions for the send and receive buffer sizes; these call through to setsockopt with SO_RCVBUF and SO_SNDBUF.
• JetByteTools::Socket::CSequencedStreamSocket::OnAttach() and JetByteTools::Socket::CSequencedStreamSocket::m_outOfSequenceWrites are now protected to make it easier to derive new socket classes from this class.

Version 5.1

• Fixed a bug in JetByteTools::Socket::CReadTimeoutStreamSocketConnectionFilter whereby sockets that hadn't had a connection established on them would throw an exception when released. This mainly manifested itself in the JetByteTools::Socket::CStreamSocketServerEx server which has lots of sockets pending accept.
• Changes to JetByteTools::IO::Mock::CMockCloseableOutputStream so that it takes an enum rather than a boolean to specify if we dump the data as a string or as a hex dump.
• Added support for STLPort 5.1.x - the location of a file that we used to use to determine if the Admin.h settings were sane has moved and so there are some changes to Admin.h to reflect this.
• Updated the docs on JetByteTools::Win32::IQueueTimers::DestroyTimer() so that it mentions that calling it on a handle which is invalid (and is set to JetByteTools::Win32::IQueueTimers::InvalidHandleValue) will cause an exception. We may change this in future so that it's allowed (in the same way that delete 0 is legal...).
• Added a note to JetByteTools::IO::CAsyncFileWriter to remind me to investigate using InterlockedAdd64...
• Added some .cvsignore files that seem to end up in the exported version of a release...
• Adjusted how and when the contents of JB_MSWSock.h is used. This was originally included to make it possible to compile without a copy of the Platform SDK installed and was a copy of the mswsock.h file from the Platform SDK (it was bound to end in tears...). Now it seems that the version of mswsock.h in the latest Platform SDK has changed and so this file causes issues. I haven't tried a build with the latest Platform SDK yet, so this 'fix' may not help, but basically unless you have JETBYTE_NO_PLATFORM_SDK defined as 1 then JB_MSWSock.h simply includes mswsock.h, which is probably how it should always have been...
• Added these release notes...

Version 5.0

• Major refactoring - you'll need to port to it, if there's enough demand I'll write a porting guide... No 'derived server' compatible with the free version of the code, but then that's probably been the case for some time.
• Moved most of the inheritance based class extension to be based on explicit callback interfaces instead. See here.
• All connection manager and server callbacks now recieve references rather than pointers where appropriate.
• Name changes for some callbacks; ReadCompleted() is now OnReadCompleted(), etc.
• Separated the filtering interface so that it's easier and clearer to use. See here.
• Added doxygen documentation.

There were no release notes prior to version 5.0

---