DjVuPortcaster Class Reference

Maintains associations between ports. More...

#include <DjVuPort.h>


Public Member Functions
void	add_alias (const DjVuPort *port, const GUTF8String &alias)
void	add_route (const DjVuPort src, DjVuPort dst)
GP< DjVuPort >	alias_to_port (const GUTF8String &name)
void	clear_aliases (const DjVuPort *port)
void	copy_routes (DjVuPort dst, const DjVuPort src)
void	del_port (const DjVuPort *port)
void	del_route (const DjVuPort src, DjVuPort dst)
	DjVuPortcaster (void)
virtual GP< DjVuFile >	id_to_file (const DjVuPort *source, const GUTF8String &id)
virtual GURL	id_to_url (const DjVuPort *source, const GUTF8String &id)
GP< DjVuPort >	is_port_alive (DjVuPort *port)
virtual void	notify_chunk_done (const DjVuPort *source, const GUTF8String &name)
virtual void	notify_decode_progress (const DjVuPort *source, float done)
virtual void	notify_doc_flags_changed (const class DjVuDocument *source, long set_mask, long clr_mask)
virtual bool	notify_error (const DjVuPort *source, const GUTF8String &msg)
virtual void	notify_file_flags_changed (const class DjVuFile *source, long set_mask, long clr_mask)
virtual void	notify_redisplay (const class DjVuImage *source)
virtual void	notify_relayout (const class DjVuImage *source)
virtual bool	notify_status (const DjVuPort *source, const GUTF8String &msg)
GPList< DjVuPort >	prefix_to_ports (const GUTF8String &prefix)
virtual GP< DataPool >	request_data (const DjVuPort *source, const GURL &url)
virtual	~DjVuPortcaster (void)
Static Public Member Functions
static void	clear_all_aliases (void)
static DjVuPortcaster *	get_portcaster (void)

Detailed Description

Maintains associations between ports.

It monitors the status of all ports (have they been destructed yet?), accepts requests and notifications from them and forwards them to destinations according to internally maintained map of routes.

The caller can modify the route map any way he likes (see {add_route}(), {del_route}(), {copy_routes}(), etc. functions). Any port can be either a sender of a message, an intermediary receiver or a final destination.

When a request is sent, the DjVuPortcaster# computes the list of destinations by consulting with the route map. Notifications are only sent to ``alive'' ports. A port is alive if it is referenced by a valid {GP} smartpointer. As a consequence, a port usually becomes alive after running the constructor (since the returned pointer is then assigned to a smartpointer) and is no longer alive when the port is destroyed (because it would not be destroyed if a smartpointer was referencing it).

Destination ports are sorted according to their distance from the source. For example, if port { A} is connected to ports { B} and { C} directly, and port { B} is connected to { D}, then { B} and { C} are assumed to be one hop away from { A}, while { D} is two hops away from { A}.

In some cases the requests and notifications are sent to every possible destination, and the order is not significant (like it is for {notify_file_flags_changed}() request). Others should be sent to the closest destinations first, and only then to the farthest, in case if they have not been processed by the closest. The examples are {request_data}(), {notify_error}() and {notify_status}().

The user is not expected to create the DjVuPortcaster# itself. He should use {get_portcaster}() global function instead.

Definition at line 356 of file DjVuPort.h.

Constructor & Destructor Documentation

DjVuPortcaster::DjVuPortcaster ( void )

The default constructor.

Definition at line 246 of file DjVuPort.cpp.

DjVuPortcaster::~DjVuPortcaster ( void ) [virtual]

Definition at line 250 of file DjVuPort.cpp.

Member Function Documentation

void DjVuPortcaster::add_alias	(	const DjVuPort *	port,
		const GUTF8String &	alias
	)

Assigns one more {alias} for the specified {DjVuPort}.

{Aliases} are names, which can be used later to retrieve this {DjVuPort}, if it still exists. Any {DjVuPort} may have more than one {alias}. But every {alias} must correspond to only one {DjVuPort}. Thus, if the specified alias is already associated with another port, this association will be removed.

Definition at line 269 of file DjVuPort.cpp.

void DjVuPortcaster::add_route	(	const DjVuPort *	src,
		DjVuPort *	dst
	)

Adds route from src# to dst#.

Whenever a request is sent or received by src#, it will be forwarded to dst# as well.

Parameters:

	src	The source
	dst	The destination

Definition at line 371 of file DjVuPort.cpp.

GP< DjVuPort > DjVuPortcaster::alias_to_port ( const GUTF8String & name )

Returns {DjVuPort} associated with the given alias#.

If nothing is known about name alias#, or the port associated with it has already been destroyed ZERO# pointer will be returned.

Definition at line 301 of file DjVuPort.cpp.

void DjVuPortcaster::clear_aliases ( const DjVuPort * port )

Removes all aliases associated with the given {DjVuPort}.

Definition at line 288 of file DjVuPort.cpp.

void DjVuPortcaster::clear_all_aliases ( void ) [static]

Removes all the aliases.

Definition at line 276 of file DjVuPort.cpp.

void DjVuPortcaster::copy_routes	(	DjVuPort *	dst,
		const DjVuPort *	src
	)

Copies all incoming and outgoing routes from src# to dst#.

This function should be called when a {DjVuPort} is copied, if you want to preserve the connectivity.

Definition at line 404 of file DjVuPort.cpp.

void DjVuPortcaster::del_port ( const DjVuPort * port )

Removes the specified port from all routes.

It will no longer be able to receive or generate messages and will be considered { "dead"} by {is_port_alive}() function.

Definition at line 337 of file DjVuPort.cpp.

void DjVuPortcaster::del_route	(	const DjVuPort *	src,
		DjVuPort *	dst
	)

The opposite of {add_route}().

Removes the association between src# and dst#

Definition at line 385 of file DjVuPort.cpp.

static DjVuPortcaster* DjVuPortcaster::get_portcaster ( void ) [inline, static]

Use this function to get a copy of the global {DjVuPortcaster}.

Definition at line 360 of file DjVuPort.h.

GP< DjVuFile > DjVuPortcaster::id_to_file	(	const DjVuPort *	source,
		const GUTF8String &	id
	)			`[virtual]`

Computes destination list for source# and calls the corresponding function in each of the ports from the destination list starting from the closest until one of them returns non-zero pointer to {DjVuFile}.

Definition at line 506 of file DjVuPort.cpp.

GURL DjVuPortcaster::id_to_url	(	const DjVuPort *	source,
		const GUTF8String &	id
	)			`[virtual]`

Computes destination list for source# and calls the corresponding function in each of the ports from the destination list starting from the closest until one of them returns non-empty {GURL}.

Definition at line 492 of file DjVuPort.cpp.

GP< DjVuPort > DjVuPortcaster::is_port_alive ( DjVuPort * port )

Returns a smart pointer to the port if port# is a valid pointer to an existing DjVuPort#.

Returns a null pointer otherwise.

Definition at line 258 of file DjVuPort.cpp.

void DjVuPortcaster::notify_chunk_done	(	const DjVuPort *	source,
		const GUTF8String &	name
	)			`[virtual]`