| synopsis || arguments || prev || next |
virtual void connect( const char * server, const char * proxy, const char * request, const char * channel_transport, const char * cache_dir)
[Declared in "../apps/compressed_io/kdu_client.h"]
Creates a new thread of execution to manage network communications and initiate a connection with the appropriate server. The function returns immediately, without blocking on the success of the connection.
The application may then monitor the value returned by is_active and is_alive to determine when the connection is actually established, if at all. The application may also monitor transfer statistics using kdu_cache::get_transferred_bytes and it may receive notification of network activities by supplying a kdu_client_notifier-derived object to the install_notifier function.
The network management thread will be terminated when the close or disconnect function is called, when the server disconnects, or when a terminal error condition arises, whichever occurs first.
It is important to realize that the internal network management thread may itself issue an error message through kdu_error. For this to be robust, the kdu_message-derived object supplied to kdu_customize_errors must throw an exception when it receives the call to kdu_message::flush with end_of_message true. The implementation of the kdu_message-derived object should be thread-safe and should be able to successfully deliver its messages, regardless of the thread from which it is invoked. These conditions should not be onerous on application developers.
The present function may itself issue a terminal error message through kdu_error if there is something wrong with any of the supplied arguments. For this reason, interactive applications should generally provide try/catch protection when calling this function.
Holds the host name or IP address of the server to be contacted. The server string may contain an optional port number suffix, in which case it has the form <host name or IP address>:<port>. The default HTTP port number of 80 is otherwise assumed. Communication with this machine proceeds over HTTP, and may involve intermediate proxies, as described in connection with the proxy argument.
Same syntax as server, but gives the host (and optionally the port number) of the machine with which the initial TCP connection should be established. This may either be the server itself, or an HTTP proxy server. May be NULL, or point to an empty string, if no proxy is to be used.
This pointer may not be NULL or reference an empty string. The string has one of the following forms: a) <resource>; or b) <resource>?<query>. In the former case, <resource> is simply the name of the target file on the server. In the latter case, the target file name may be held in the <resource> component, or as a query field of the form "target=<name>", in which case the <resource> string may refer to a CGI script or some other identifier having meaning to the server. In any event, the complete request string may consist only of URI-legal characters and, in particular, may contain no white space characters. If necessary, non-conforming characters should be hex-hex encoded, as described in RFC2396 (Uniform Resource Identifiers (URI): Generic Syntax).
The <query> string may contain multiple fields, each of the form <name>=<value>, separated by the usual "&" character. If a <query> string contains anything other than the "target" or "subtarget" fields, it is interpreted as a one-time request. In this case, the request will be issued as-is to the server, and once the server's response is fully received, the connection will be closed. This type of request might be embedded in HTML documents as a simple URL. In this mode, any calls to post_window will be ignored, since the application is not permitted to interactively control the communications. Also, in this mode, the channel_transport argument is ignored and a session-less transaction is used.
If NULL or a pointer to an empty string or the string "none", no attempt will be made to establish a JPIP channel. In this case, no attempt will be made to establish a stateful communication session; each request is delivered to the server (possibly through the proxy) in a self-contained manner, with all relevant cache contents identified using appropriate JPIP-defined header lines. When used interactively, (nothing other than "target" or "subtarget" query fields in the request string), this mode may involve somewhat lengthy requests, and may cause the server to go to quite a bit of additional work, re-creating the context for each and every request.
If channel_transport holds the string "http" and the request string does not contain any query request fields other than "target" or "subtarget", the client's first request asks for a channel with HTTP as the transport. If the server refuses to grant a channel, communication will continue as if the channel_transport argument had been NULL.
If channel_transport holds the string "http-tcp", the behaviour is the same as if it were "http", except that a second TCP channel is established for the return data. This transport variant is somewhat more efficient for both client and server, but requires an additional TCP channel and cannot be used from within organizations which mandate that all external communication proceed through HTTP proxies. If the server does not support the "http-tcp" transport, it may fall back to an HTTP transported channel. This is because the client's request to the server includes a request field of the form "cnew=http-tcp,http", giving the server both options.
It is worth noting that wherever a channel is requested, the server may respond with the address of a different host to be used in all future requests.
If non-NULL, this argument provides the path name for a directory in which cached data may be saved at the end of an interactive communication session. The directory is also searched at the beginning of an interactive session, to see if information is already available for the image in question. If the argument is NULL, or points to an empty string, the cache contents will not be saved and no previously cached information may be re-used here. Files written to or read from the cache directory have the ".kjc" suffix, which stands for (Kakadu JPIP Cache). These files commence with some details which may be used to re-establish connection with the server, if necessary (not currently implemented) followed by the cached data itself, stored as a concatenated list of data-bins. The format of these files is private to the current implementation and subject to change in subsequent releases of the Kakadu software, although the files are at least guaranteed to have an initial header which can be used for version-validation purposes.