[ Previous document | Content Table | Next document ]

19    Universal Content Providers

               

19.1    The Hierarchy Content Provider

19.1.1    Preface

The Hierarchy Content Provider (HCP) implements a content provider for the Universal Content Broker (UCB). It provides access to a persistent, customizable hierarchy of contents.

19.1.2    HCP Contents

The HCP provides three different types of contents: link, folder and root folder.

  1. An HCP link is a content that "points" to another UCB content. It is always contained in an HCP Folder. An HCP Link has no children.

  2. An HCP folder is a container for other HCP Folders and HCP Links.

  3. There is at least one instance of an HCP root folder at a time. All other HCP contents are children of this folder. The HCP root folder  contains HCP folders and links. It has the URL vnd.sun.star.hier:/.


Illustration A.1

19.1.3    Creation of New HCP Content

HCP folders and the HCP root folder implement the interface com.sun.star.ucb.XContentCreator. HCP links and HCP folders support the command "insert" allowing all the HCP folders, as well as the HCP root folder to create new HCP folders and HCP links. To create a new child of an HCP folder:

  1. The parent folder creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.star.hier-folder". To create a new link, use the type string "application/vnd.sun.star.hier-link".

  2. Set a title at the new folder or link. The new child executes the "setPropertyValues" command that sets the property Title to a non-empty value. For a link, set the property TargetURL to a non-empty value.

  3. The new child, not the parent executes the command "insert". This commits the creation process.

19.1.4    URL Scheme for HCP Contents

Each HCP content has an identifier corresponding to the following scheme:

vnd.sun.star.hier:/<path>

where <path> is a hierarchical path of the form

name>/<name>/.../<name>

where <name> is an encoded string according to the URL conventions.

Examples:

vnd.sun.star.hier:/ (The URL of the HCP Root Folder)

vnd.sun.star.hier:/Bookmarks/Sun%20Microssystems%20Home%20Page

vnd.sun.star.hier:/Workplace/Printers

19.1.5    Commands and Properties

UCB Type (returned by XContent::getContentType )

Properties

Commands

Interfaces

Link

application/
vnd.sun.star.hier-link

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

TargetURL

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

XTypeProvider

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XChild

Folder

application/
vnd.sun.star.hier-folder

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

transfer1

same as HCP Link, plus XContentCreator

Root Folder

application/
vnd.sun.star.hier-folder

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

open

transfer

same as HCP Link, plus XContentCreator

1        The "transfer" command only transfers HCP-contents to HCP folders. It does not handle contents with a URL scheme other then the HCP-URL-scheme.

19.2    The File Content Provider

19.2.1    Preface

The File Content Provider (FCP), a content provider for the Universal Content Broker (UCB), provides access to the local file system by providing file content objects that represent a directory or a file in the local file system. The FCP is able to restrict access to the file system to a number of directories shown to the client under configurable aliases.

19.2.2    File Contents

The FCP provides content representing a directory or file in the local file system.

  1. A directory contains other directories or files.

  2. A file is a container for document data or content. The FCP can not determine the MediaType property of a file content.

19.2.3    Creation of New File Contents

A content representing directories implements the interface com.sun.star.ucb.XContentCreator. A file content object supports the command "insert". To create a new directory or file in a directory:

  1. The parent directory creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.staroffice.fsys-folder". To create a new file, use the type string "application/vnd.sun.staroffice.fsys-file". A new file content object is the retun value.

  2. Set a title at the new file content object. The new child executes a "setPropertyValues" command that sets the property Title to a non-empty value.

  3. The new file content object, not the parent, executes the command "insert". This creates the corresponding physical file or directory. For files, supply the implementation of an com.sun.star.io.XInputStream with the command's parameters that provide access to the stream data.

19.2.4    URL Schemes for File Contents

The file URL Scheme

Each file content has an identifier corresponding to the following scheme:

file:///<path>

where <path> is a hierarchical path of the form

<name1>/<name>/.../<name>.

The first part of <path> ( <name1> ) is not required to denote a physically existing directory, but may be remapped to such a directory. If this is done, the FCP refuses file access for any URL whose <name1>-part is not an element of a predefined list of alias names.

The vnd.sun.star.wfs URL Scheme

In the Sun ONE Webtop, the server-side file system is addressed with vnd.sun.star.wfs URLs. The wfs stands for Webtop File System. The file URL scheme is reserved for a potential client-side file system.


Illustration A.2

The vnd.sun.star.wfs URL scheme is completely hidden from the FCP, that is, the server side FCP internally works with file URLs, like any other FCP: There is a Remote Access Content Provider (RAP) between the UCB and the FCP. The RAP, among other things, can route requests to another UCP and rewrite URLs. This feature is used so that the client of the UCB works with vnd.sun.star.wfs URLs and the FCP remains unmodified and works with file URLs, with a RAP in between that maps between those two URL schemes.

Except for the different scheme name, the syntax of the vnd.sun.star.wfs URL scheme is exactly the same as the file URL scheme.

19.2.5    Commands and Properties

UCB Type (returned by XContent::getContentType )

Properties

Commands

Interfaces

File

application/
vnd.sun.staroffice.fsys-file

[readonly] ContentType

DateCreated

DateModified

[readonly] IsDocument

[readonly] IsFolder

Size

Title

IsReadOnly

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

transfer

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XChild

XContentCreator

Directory

application/
vnd.sun.staroffice.fsys-folder

[readonly] ContentType

DateCreated

DateModified

[readonly] IsDocument

[readonly] IsFolder

Size

Title

IsReadOnly

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XChild

19.3    The FTP Content Provider

19.3.1    Preface

The FTP content provider implements a content provider for the Universal Content Broker (UCB). It provides access to the contents, folders and documents, made available by FTP servers.

19.3.2    FTP Contents

The FTP Content Provider provides three different types of contents: accounts, folders and documents.

  1. An FTP account is a content that represents an account for an FTP server. An account is uniquely determined by a combination of a user name and the host name of the FTP server. Anonymous FTP accounts have the string "anonymous" as a user name. An FTP account also represents the base directory, that is, the directory that is selected when the user logs in to the FTP server, and behaves like an FTP folder.

  2. An FTP folder is a content that represents a directory on an FTP server. An FTP folder never has a content stream, but it can have FTP folders and FTP documents as children.

  3. An FTP document is a content that represents a single file on an FTP server. An FTP document always has a content stream and never has children.


Illustration A.3

19.3.3    Creation of New FTP Content

FTP accounts and FTP folders implement the interface com.sun.star.ucb.XContentCreator. FTP folders and FTP documents support the command "insert"allowing all the FTP accounts and FTP folders to create new FTP folders and FTP documents. To create a new child of an FTP account or FTP folder:

  1. The folder creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.staroffice.ftp-folder". To create a new document, use the type string "application/vnd.sun.staroffice.ftp-file".

  2. Set a title at the new folder or document. The new child executes a "setPropertyValues" command that sets the property Title to a non-empty value.

  3. The new child, not the parent, executes the command "insert". This commits the creation process. For documents, supply an com.sun.star.io.XInputStream, whose contents are transferred to the FTP server with the command's parameters.

FTP accounts cannot be created the way new FTP folders or FTP documents are created. When you call the FTP content provider's queryContent() method with the URL of an FTP account, a content object representing that account, user name and host combination, is automatically created. The same as the URL of an already existing FTP folder or FTP document.

19.3.4    URL Scheme for FTP Contents

Each FTP content has an identifier corresponding to the following scheme
(see also RFCs 1738, 2234, 2396, and 2732):

ftp-URL ::=             "ftp://" login *("/" segment)

login ::=               [user [":" password] "@"] hostport

user ::=                *(escaped / unreserved / "$" / "&" / "+" / "," / ";" / "=")

password ::=            *(escaped / unreserved / "$" / "&" / "+" / "," / ";" / "=")

hostport ::=            host [":" port]

host ::=                incomplete-hostname / hostname / IPv4address

incomplete-hostname ::= *(domainlabel ".") domainlabel

hostname ::=            *(domainlabel ".") toplabel ["."]

domainlabel ::=         alphanum [*(alphanum / "-") alphanum]

toplabel ::=            ALPHA [*(alphanum / "-") alphanum]

IPv4address ::=         1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT

port ::=                *DIGIT

segment ::=             *pchar

pchar ::=               escaped / unreserved / "$" / "&" / "+" / "," / ":" / "=" / "@"

escaped ::=             "%" HEXDIG HEXDIG

unreserved ::=          alphanum / mark

alphanum ::=            ALPHA / DIGIT

mark ::=                "!" / "'" / "(" / ")" / "*" / "-" / "." / "_" / "~"

FTP accounts have a login part, optionally followed by a single slash, and no segments. FTP folders have a login part followed by one or more nonempty segments that must be followed by a slash. FTP documents have a login part followed by one or more nonempty segments that must not be followed by a slash, that is, the FTP content provider uses a potential final slash of a URL to distinguish between folders and documents. Note that this is subject to change in future versions of the provider.

Examples:

ftp://me@ftp.host

The account of user "me" on the FTP server "ftp.host".

ftp://ftp.host/pub/doc1.txt

A document on an anonymous FTP account.

ftp://me:secret@ftp.host/secret-documents/

A folder within the account of user "me" with the password specified directly in the URL. Not recommended.

19.3.5    Commands and Properties

UCB Type (returned by XContent::getContentType )

Properties

Commands

Interfaces

Account

application/
vnd.sun.staroffice.ftp-box

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

UserName

Password

FTPAccount1

ServerName

ServerBase2

[readonly] DateCreated

[readonly] DateModified

[readonly] FolderCount

[readonly] DocumentCount

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

open

transfer3

XTypeProvider

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XContentCreator

Folder

application/
vnd.sun.staroffice.ftp-folder

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

[readonly] DateCreated

[readonly] DateModified

[readonly] FolderCount

[readonly] DocumentCount

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

transfer

same as FTP Account

plus

XChild

Docu-ment

application/
vnd.sun.staroffice.ftp-file

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

Title

[readonly] DateCreated

[readonly] DateModified

[readonly] IsReadOnly

[readonly] Size

MediaType

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

same as FTP Folder minus

XContentCreator

1        The property FTPAccount is similar to Password. Some FTP servers not only require authentication through a password, but also through a second token called an "account".

2        The property ServerBase is used to override the default directory associated with an FTP account.

3        The "transfer" command only transfers contents within one FTP Account. It cannot transfer contents between different FTP accounts or between the FTP content provider and another content provider.

19.4    The WebDAV Content Provider

19.4.1    Preface

The WebDAV Content Provider (DCP) implements a content provider for the Universal Content Broker (UCB). An overview is provided at URLs http://www.webdav.org and http://www.fileangel.org/docs/DAV_2min.html. It provides access to WebDAV and standard HTTP servers. The DCP communicates with the server by using the WebDAV protocol that is an extension to the HTTP protocol, or by using the plain HTTP protocol if the server is not WebDAV-enabled.

19.4.2    DCP Contents

The DCP provides two types of content: a folder or document that corresponds to a collection or non-collection, of nodes and leafs, in WebDAV, respectively.

  1. A DCP folder is a container for other DCP Folders or Documents.

  2. A DCP document is a container for document data or content. The data or content can be any type. A WebDAV server, like an HTTP server, does not mandate what type of data or content is contained within Documents. The type of data or content is defined by the MediaType property which is different from the content type returned from the getContentType() method. The MediaType property is mapped to the equivalent WebDAV property and the WebDAV server calculates the value.


Illustration A.4

19.4.3    Creation of New DCP Contents

DCP folders implement the interface com.sun.star.ucb.XContentCreator. DCP documents and DCP folders support the command "insert". To create a new child of a DCP folder:

  1. The parent folder creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.star.webdav-collection". To create a new document, use the type string "application/http-content".

  2. Set a title for the new folder or document. The new child executes a "setPropertyValues" command that sets the property Title to a non-empty value.

  3. The new child, not the parent, executes the command "insert". This commits the creation process and makes the newly-created content on the WebDAV server persistent.

19.4.4    Authentication

DAV resources that require authentication are accessed using the interaction handler mechanism of the UCB. The DAV content calls an interaction handler supplied by the client to let it handle an authentication request. The implementation of the interaction handler collects the user name or password from a location, for example, a login dialog, and supplies this data as an interaction response.

19.4.5    Property Handling

In addition to the mandatory UCB properties, the DCP supports reading and writing all DAV live and dead properties. Some DAV live properties are mapped in addition to the UCB properties and conversely, that is,  DAV:creationdate is mapped to DateCreated. Adding and removing dead properties is also supported by the implementation of the XPropertyContainer interface of a DCP content.

Property Values:

The DCP cannot determine the semantics of unknown properties, thus the values of such properties will always be presented as plain text, as they were returned from the server.

Namespaces:

The following namespaces are known to the DCP:

Properties with these namespaces are addressed using a UCB property name which is the concatenation of namespace and name, that is, DAV:getcontentlength.

Dead properties with namespaces that are not well-known to the DCP are addressed using a special UCB property name string, that contains both the namespace and the property name. A special property name string must be similar to the following:

<prop:the_propname xmlns:prop="the_namespace">

The DCP internally applies the namespace http://ucb.openoffice.org/dav/props/ to all UCB property names that:

For example, a client does an addProperty( .... "MyAdditionalProperty" ... ). The resulting DAV property has the name MyAdditionalProperty, its namespace is http://ucb.openoffice.org/dav/props/. However, the DCP client never sees that namespace, but the client can always use the simple name MyAdditionalProperty.

DAV / UCB Property Mapping:

DAV:creationdate

DateCreated

DAV:getlastmodified

DateModified

DAV:getcontenttype

MediaType

DAV:getcontentlength

Size

DAV:resourcetype

(used to set IsFolder, IsDocument, ContentType)

19.4.6    URL Scheme for DCP Contents

Each DCP content has an identifier corresponding to the following scheme:

vnd.sun.star.webdav://host:port/<path>

where <path> is a hierarchical path of the form

<name>/<name>/.../<name>

where <name> is an encoded string according to the URL conventions.

It is also possible to use standard HTTP URLs. The implementation determines if the requested resource is DAV enabled.

Examples:

vnd.sun.star.webdav://localhost/davhome/

vnd.sun.star.webdav://davserver.com/Documents/report.sdw

http://davserver.com/Documents/report.sdw


Note that the WebDAV URL namespace model is the same as the HTTP URL namespace model.

19.4.7    Commands and Properties

UCB Type (returned by XContent::getContentType )

Properties

Commands

Interfaces

Docu-ment

application/
http-content

[readonly] ContentType

[readonly] DateCreated

[readonly] DateModified

[readonly] IsDocument

[readonly] IsFolder

[readonly] MediaType

[readonly] Size

'Title'

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

XTypeProvider

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XChild

Folder

application/
vnd.sun.star.webdav-collection

[readonly] ContentType

[readonly] DateCreated

[readonly] DateModified

[readonly] IsDocument

[readonly] IsFolder

[readonly] MediaType

[readonly] Size

Title

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

"transfer

same as DCP Folder, plus

XContentCreator

19.5    The Package Content Provider

19.5.1    Preface

The Package Content Provider (PCP) implements a content provider for the Universal Content Broker (UCB). It provides access to the content of ZIP and JAR archive files. It maybe extended to support other packages, such as OLE storages, in the future.

19.5.2    PCP Contents

The PCP provides two different types of contents: stream and folder.

  1. A PCP stream is a content that represents a file inside a package. It is always contained in a PCP folder. A PCP stream has no children.

  2. A PCP folder is a container for other PCP folders and PCP streams.


Illustration A.5

19.5.3    Creation of New PCP Contents

PCP folders implement the interface com.sun.star.ucb.XContentCreator. PCP streams and PCP folders support the command "insert", therefore all PCP folders can create new PCP folders and PCP streams. To create a new child of a PCP folder:

  1. The parent folder creates a new content by calling its createNewContent() method. The content type for new folders is "application/vnd.sun.star.pkg-folder". To create a new stream, use the type string "application/vnd.sun.star.pkg-stream".

  2. Set a title for the new folder or stream. The new child executes a "setPropertyValues" command that sets the property Title to a non-empty value.

  3. The new child, not the parent, executes the command "insert". This commits the creation process. For streams, supply the implementation of an com.sun.star.io.XInputStream with the command parameters that provide access to the stream data.

Another convenient method to create streams is to assemble the URL for the new content where the last part of the path becomes the title of the new stream and obtain a Content object for that URL from the UCB. Then, let the content execute the command "insert". The command fails if you set the command parameter "ReplaceExisting" to false and there is already a stream with the title given by the content's URL.

19.5.4    URL Scheme for PCP Contents

Each PCP content has an identifier corresponding to the following scheme:

package-URL ::=         "vnd.sun.star.pkg://" orig-URL [ abs-path ]

abs-path ::=         "/" path-segments

path-segments ::= segment * ( "/" segment )

segment ::=       pchar

pchar ::=         unreserved | escaped | ":" | "@" | "&" | "=" | "+" | "$" | ","

unreserved ::=    alphanum | mark

mark ::=          "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"

escaped ::=       "%" hex hex

orig-URL        1 ::=     * ( unreserved | escaped | "$" | "," | ";" | ":" | "@" | "&" | "&" | "=" | "+" )

Examples:

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/

The root folder of the package located at file:///e:/my.xsw.

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/Content

The folder or stream named "Content" that is contained in the root folder of the package located at file:///e:/my.xsw.

vnd.sun.star.pkg://file:%2F%2F%2Fe:%2Fmy.xsw/Content%20A

The folder or stream named "Content A" that is contained in the root folder of the package located at file:///e:/my.xsw.

19.5.5    Commands and Properties

UCB Type (returned by XContent::getContentType )

Properties

Commands

Interfaces

Stream

application/
vnd.sun.star.pkg-stream

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

MediaType

[readonly] Size

Title

Compressed1

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

XTypeProvider

XServiceInfo

XComponent

XContent

XCommandProcessor

XPropertiesChangeNotifier

XPropertyContainer

XPropertySetInfoChangeNotifier

XCommandInfoChangeNotifier

XChild

Folder

application/
vnd.sun.star.pkg-folder

[readonly] ContentType

[readonly] IsDocument

[readonly] IsFolder

MediaType

[readonly] Size

Title

getCommandInfo

getPropertySetInfo

getPropertyValues

setPropertyValues

insert

delete

open

transfer2

flush3

same as PCP Stream, plus XContentCreator

1        The property Compressed is introduced by package streams to explicitly state if you want a stream to be compressed or not. The default value of this property is determined according to the value suggested by the underlying packager implementation.

2        The "transfer" command only transfers PCP folders or streams to other PCP folders. It does not handle contents with a URL scheme other then the PCP-URL scheme.

3        'flush' is a command introduced by the PCP Folder. It takes a void argument and returns void. This command is used to write unsaved changes to the underlying package file. Note that in the current implementation, PCP contents never flush automatically! Operations which require a flush to become persistent are: "setPropertyValues(Title | MediaType)", "delete", "insert".

19.6    The Help Content Provider

19.6.1    Preface

Currently, the Help Content Provider has the following responsibilities:

  1. It is the interface to a search engine that allows a full-text search, including searching specific scopes, such as headers. The range of accessible scopes depends on the indexing process and is currently not changeable after setup.

  2. It delivers a keyword index to its clients.

  3. The actual helpcontent has media type "text/html," with some images of type "image/gif" embedded. The content is generated from packed xml files that have to be transformed according to a xsl-transformation to produce the resulting XHTML. There is a cascading style sheet used for formatting the XHTML files of media type "text/css".

  4. (It provides its clients the modules for which help is available.

19.6.2    Help Content Provider Contents

The responsibilities mentioned above are fulfilled by providing different kinds of content objects to the client, namely:

These contents are described below.

19.6.3    URL Scheme for Help Contents

Each Help content has an identifier corresponding to the following scheme:

URL ::=          scheme delimiter path? query? anchor?

scheme ::=       "vnd.sun.star.help"

delimiter ::=    "://" | ":/"

path ::=         module ( "/" id )?

query ::=        "?" key-value-list?

keyvaluelist ::= keyvalue ( "&" keyvalue )?

keyvalue ::=     key "=" value

anchor ::=       "#" anchor-name

Currently, to have a fault-tolerant system, some enveloping set of this is allowed, but without carrying more information.

Examples:

vnd.sun.star.help://?System=WIN&Language=de

vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=Heading

vnd.sun.star.help://portal/4711?System=UNIX&Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal

Some information must be given in every URL, namely the value of the keys "System"/"Language."

"System" may be one of "UNIX," "WIN," "OS2" and "MAC". This key parameterizes the XSL transformation applied to the help filesand their content changes according to this parameter, and is mandatory only for helpcontents delivering XHTML-files. This may change in the future.

"Language" is coded as ISO639 language code, optionally followed by "-" and ISO3166 country code. Only the language code part of "Language" is used and directly determines the directory, which is relative to the installation path where the help files are found.

In the following, the term "help-directory" is used to determine the directory named "help" in the office/portal installation. The term "help-installation-directory" is used to denote the particular language-dependent subdirectory of the help-directory that contains the actual help files as a packed jar file, the index, the config files and some other items not directly used by the help content provider.

19.6.4    Properties and Commands

Every creatable content can execute the following commands. It isnot constrained to a particular URL-scheme:

com::sun::star::ucb::XCommandInfo getCommandInfo()

com::sun::star::beans::XPropertySetInfo getPropertySetInfo()

com::sun::star::sdbc::XRow getPropertyValues([in] sequence< com::sun::star::beans::Property > )

void setPropertyValues([in] sequence< com::sun::star::beans::PropertyValue > )

These commands repeat the information given in the following. The available properties and commands are explained by the following URL examples:

Root Content

vnd.sun.star.help://?System=WIN&Language=de

Properties:

Name

Type

value

'Title'

string

"root"

'IsFolder'

boolean

true

'IsDocument'

boolean

true

'ContentType'

string

"application/vnd.sun.star.help"

'MediaType'

string

"text/css"

Commands:

Return Type

Name

Argument Type

XDynamicResultSet

open1

OpenCommandArgument2

1        Return value of this command contains the modules available in the particular installation for the requested language. The modules are currently determined by looking for the files in the help-installation-directory matching "*.db", with the exception of the file "picture.db".

Generally, a module corresponds to a particular application, namely, if the writer application is installed, there should be a module "vnd.sun.star.help://swriter" and so forth.

The written XOutputStream or the set XInputStream (set at XActiveDataSink) makes the cascading style sheet available, which is used to format the XHTML files. Physically, the stream contains the content of the file custom.css in the help-directory of the office or portal installation.

Only the key "Language" is used. Any other key may be set, but is ignored.

Module Content

vnd.sun.star.help://swriter?System=WIN&Language=de&Query=text&HitCount=120&Scope=
Heading

Properties:

Name

Type

value

Title

string

determined from config file in help-installation-directory

IsFolder

boolean

true

IsDocument

boolean

false

ContentType

string

"application/vnd.sun.star.help"

KeyWordList

sequence< string >

(See below)

KeyWordRef

sequence< sequence < string > >

(See below)

KeyWordAnchorForRef

sequence< sequence < string > >

(See below)

KeyWordTitleForRef

sequence< sequence < string > >

(See below)

SearchScopes

sequence< string >

(See below)

The help files contain specially marked keywords. The alphabetically sorted list of keywords is contained in the property KeywordList.

For example, you are looking for keyword KeywordList[i], where i is an integer. The help module in which this keyword should be found is determined by the module part of the content URL, "swriter" in our example. Now KeywordRef[i] contains a list of document ids, where the document belonging to that id contains the keyword string "docid = KeywordRef[i][j]".

The location in the XHTML document where this particular keyword refers to is marked by an HTML anchor element:

<A name="anchor"/>

Here the anchor is given by the string "anchor = KeywordAnchorForRef[i][j]".

For our example, the URL of the j document in the swriter module containing the keyword Keyword[i] is determined as vnd.sun.star.help://swriter/docid?System=WIN&Language=de#anchor.

The keys "HitCount", "Query" and "Scope" have no value with regards to the keywords.

The title of the resulting document is determined directly without having to instantiate the content by the value of "KeywordTitleForRef[i][j]".

The module contents are also the interface to the search engine. A number of additional keys in the URL are necessary, namely the keys:

The value of Scope should be one of the strings given by the property SearchScopes, currently "Heading" or "FullText". Leaving the key undefined defaults to a full-text search, Setting it to "Heading" means to search in only the document titles.

There may be any number of Query key definitions in the URL. Many Query keys determine a query search, first for documents containing all the values, then searching for those containing only subsets of all the values. The requested number of results is determined by the value of the key HitCount. The actual returned number may be smaller. The interface to the results returned by the search engine is given by an com.sun.star.ucb.XDynamicResultSet, which is the return value of the command "open":

Return Type

Name

Argument Type

XDynamicResultSet

open

OpenCommandArgument2

XHTML Content or Picture Content

vnd.sun.star.help://portal/4711?System=UNIX&Language=en_US&HelpPrefix=http%3A%2F%2Fportal%2Fportal%2F

Properties:

Name

Type

value

Title

string

determined from database

IsFolder

boolean

false

IsDocument

boolean

true

ContentType

string

"application/vnd.sun.star.help"

MediaType1

string

"text/html" or "image/gif"

1        The MediaType "image/gif" corresponds to a URL which contains a module part "picture", as opposed to "portal" in the example.

Commands:

Return Type

Name

Argument Type

void

"open"1

OpenCommandArgument2

1        Returns the transformed XHTML-content, or the gif-content of a PictureContent.

There is one special document for every module, namely those named start (replace 4711 by start in our example). It identifies the main help page for every module.

There is an additional key named HelpPrefix. If set, every link in a generated document pointing to another help-document, either XHTML or image document, is first encoded and then prefixed by the URL-decoded form of the value of this key. This key is only used by Sun One Webtop.

[ Previous document | Content Table | Next document ]