LibreOffice Developer's Guide: Appendix C - Universal Content Providers

The Universal Content Providers consist of the:

Hierarchy content
File content
FTP content
WebDAV content
Package content
Help content

The Hierarchy Content Provider

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.

HCP Contents

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

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.
An HCP folder is a container for other HCP Folders and HCP Links.
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:/.

A Hierarchy Content Provider

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:

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".
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.
The new child, not the parent executes the command "insert". This commits the creation process.

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

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 transfer¹	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

¹ 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.

The File Content Provider

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.

File Contents

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

A directory contains other directories or files.
A file is a container for document data or content. The FCP can not determine the MediaType property of a file content.

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:

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 return value.
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.
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.

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.

URL schemes for file contents

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.

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

The FTP Content Provider

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.

FTP Contents

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

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.
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.
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.

Overview of an FTP Content Provider

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:

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".
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.
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.

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.

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 FTPAccount¹ ServerName ServerBase² [readonly] DateCreated [readonly] DateModified [readonly] FolderCount [readonly] DocumentCount	getCommandInfo getPropertySetInfo getPropertyValues setPropertyValues open transfer³	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
Document	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

¹ 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".

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

³ 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.

The WebDAV Content Provider

The WebDAV Content Provider (DCP) implements a content provider for the Universal Content Broker (UCB). An overview is provided at URL http://www.webdav.org. 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.

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.

A DCP folder is a container for other DCP Folders or Documents.
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.

WebDav Content Provider

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:

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".
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.
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.

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 username or password from a location, for example, a login dialog, and supplies this data as an interaction response.

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:

DAV:
http://apache.org/dav/props/

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:

are not predefined by the UCB API.
do not start with a well-known namespace.
do not use the special property name string to encode namespace and name.

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)

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:
Note that the WebDAV URL namespace model is the same as the HTTP URL namespace model.

Commands and Properties

	UCB Type (returned by XContent::getContentType )	Properties	Commands	Interfaces
Document	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

The Package Content Provider

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.

PCP Contents

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

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.
A PCP folder is a container for other PCP folders and PCP streams.

A Package Content Provider

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:

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".
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.
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.

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-URL1 ::=     * ( 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.

You may use the service com.sun.star.uri.VndSunStarPkgUrlReferenceFactory as a helper to correctly encode the URL.

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 Compressed¹	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 transfer² flush³	same as PCP Stream, plus XContentCreator

¹ 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.

² 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.

³ '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".

The Help Content Provider

Currently, the Help Content Provider has the following responsibilities:

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.
It delivers a keyword index to its clients.
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".
It provides its clients the modules for which help is available.

Help Content Provider Contents

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

a root content giving general information about the installed help files
a module content serving as the interface to all search functionality
picture and XHTML Contents providing the actual content of the transformed help files and pictures

These contents are described below.

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.

Properties and Commands

Every creatable content can execute the following commands. It is not 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	open¹	OpenCommandArgument2

¹ 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:

HitCount
Query
Scope

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"
MediaType¹	string	"text/html" or "image/gif"

¹ 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"¹	OpenCommandArgument2

¹ 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.

Content on this page is licensed under the Public Documentation License (PDL).