Implements a full JPIP network client, building on
the services offered by
kdu_cache. The following is a brief summary of the way in which
this object is expected to be used:
-
The client application uses the
connect function to start a new thread of execution which
will communicate with the remote server. The cache
may be used immediately, if desired, although its contents
will remain empty until the server connection has been
established.
-
The client application determines whether or not the
remote object is a JP2-family file, by invoking
kdu_cache::get_databin_length on meta data-bin 0, using its
is_complete member to determine whether a returned length of 0
means that meta data-bin 0 is empty, or simply that
nothing is yet known about the data-bin, based on communication
with the server so far (the server might not even have
been connected yet).
-
If the
kdu_cache::get_databin_length function returns a length of 0 for meta data-bin 0,
and the data-bin is complete, the image corresponds
to a single raw JPEG2000 code-stream and the client
application must wait until the main header data-bin
is complete, calling
kdu_cache::get_databin_length again (this time querying the state of the code-stream
main header data-bin) to determine when this has occurred.
At that time, the present object may be passed directly
to
kdu_codestream::create.
-
If the
kdu_cache::get_databin_length function identifies meta data-bin 0 as non-empty,
the image source is a JP2-family file. The client application
uses the present object to open a
jp2_family_src object, which is then used to open a
jp2_source object (or any other suitable file format parser derived
from
jp2_input_box). The application then calls
jp2_source::read_header until it returns true, meaning that the cache has
sufficient information to read both the JP2 file header
and the main header of the embedded JPEG2000 code-stream.
At that point, the
jp2_source object is passed to
kdu_codestream::create.
-
At any point, the client application may use the
disconnect function to disconnect from the server, while continuing
to use the cache, or the
close function to both disconnect from the server (if still
connected) and discard the contents of the cache.
The
kdu_client object also provides a number of status functions
for monitoring the state of the network connection.
These are
-
is_active — returns true from the point at which
connect is called, remaining true until
close is called, even if the connection with the server
has been dropped, or was never completed.
-
is_alive — returns true from the point at which
connect is called, remaining true until the network management
thread terminates. This happens if
close is called, if the network connection is explicitly
terminated by a call to
disconnect, if the server terminates the connection, or if the
original connection attempt failed to complete.
-
is_idle — returns true if the server has finished responding
to all pending requests, but the connection is still
alive.