Logo Search packages:      
Sourcecode: djvulibre version File versions

void DjVuDocument::start_init ( const GURL url,
GP< DjVuPort port = 0,
DjVuFileCache cache = 0 

Initializes the DjVuDocument# object using an existing document. This function should be called once after creating the object. The url# should point to the real data, and the creator of the document should be ready to return this data to the document if it's not stored locally (in which case DjVuDocument# can access it itself).

{ Initializing thread} In a single-threaded application, the start_init()# function performs the complete initialization of the DjVuDocument# before it returns. In a multi-threaded application, though, it initializes some internal variables, requests data for the document and starts a new {initializing} thread, which is responsible for determining the document type and structure and completing the initialization process. This additional complication is justified in the case of the DjVu plugin because performing initialization requires data and in the plugin the data can be supplied by the main thread only. Thus, if the initialization was completed by the main thread, the plugin would run out of data and block.

{ Stages of initialization} Immediately after the start_init()# function terminates, the DjVuDocument# object is ready for use. Its functionality will not be complete (until the initializing thread finishes), but the object is still very useful. Such functions as {get_page}() or {get_djvu_file}() or {id_to_url}() may be called before the initializing thread completes. This allows the DjVu plugin start decoding as soon as possible without waiting for all data to arrive.

To query the current stage of initialization you can use {get_doc_flags}() function or listen to the notify_doc_flags_changed()# notifications distributed with the help of {DjVuPortcaster}. To wait for the initialization to complete use {wait_for_complete_init}(). To stop initialization call {stop_init}().

{ Querying data} The query for data is done using the communication mechanism provided by {DjVuPort} and {DjVuPortcaster}. If port# is not ZERO#, then the request for data will be forwarded to it. If it { is} ZERO# then DjVuDocument# will create an internal instance of {DjVuSimplePort} and will use it to access local files and report errors to stderr#. In short, if the document file is stored on the local hard disk, and you're OK about reporting errors to stderr#, you may pass ZERO# pointer to {DjVuPort} as DjVuDocument# can take care of this situation by itself.

{ The URL} Depending on the document type the url# should point to: {itemize} { Old bundled} and { New bundled} formats: to the document itself. { Old indexed} format: to any page of the document. { New indirect} format: to the top-level file of the document. If (like in the {old indexed} format) you point the url# to a page, the page {will} be decoded, but it will {not} be recognized to be part of the document. {itemize}

url The URL pointing to the document. If the document is in a {bundled} format then the URL should point to it. If the document is in the {old indexed} format then URL may point to any page of this document. For {new indirect} format the URL should point to the top-level file of the document.
port If not ZERO#, all requests and notifications will be sent to it. Otherwise DjVuDocument# will create an internal instance of {DjVuSimplePort} for these purposes. It's OK to make it ZERO# if you're writing a command line tool, which should work with files on the hard disk only because DjVuDocument# can access such files itself.
cache It's used to cache decoded {DjVuFile}s and is actually useful in the plugin only.

Definition at line 154 of file DjVuDocument.cpp.

References DjVuPortcaster::add_route(), GThread::create(), GPEnabled::get_count(), DjVuPort::get_portcaster(), GURL::get_string(), GURL::is_empty(), GURL::is_local_file_url(), and DjVuPortcaster::request_data().

Referenced by create(), and init().

   DEBUG_MSG("DjVuDocument::start_init(): initializing class...\n");
   if (init_started)
      G_THROW( ERR_MSG("DjVuDocument.2nd_init") );
   if (!get_count())
      G_THROW( ERR_MSG("DjVuDocument.not_secure") );
     if (!init_data_pool)
       G_THROW( ERR_MSG("DjVuDocument.empty_url") );
      // Initialize
   DjVuPortcaster * pcaster=get_portcaster();
   if (!xport)
     xport=simple_port=new DjVuSimplePort();
   pcaster->add_route(this, xport);
   pcaster->add_route(this, this);

     init_data_pool=pcaster->request_data(this, init_url);
       if(!init_url.is_empty() && init_url.is_local_file_url() && djvu_import_codec)
     if (!init_data_pool) 
       G_THROW( ERR_MSG("DjVuDocument.fail_URL") "\t"+init_url.get_string());
      // Now we say it is ready

   init_thr.create(static_init_thread, this);

Generated by  Doxygen 1.6.0   Back to index