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

    From The Document Foundation Wiki

    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.

    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:/.
    A Hierarchy Content Provider

    Creation of New HCP Content

    HCP folders and the HCP root folder implement the interface <idl>com.sun.star.ucb.XContentCreator</idl>. 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.

    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

    <idls>com.sun.star.lang.XTypeProvider</idls>

    <idls>com.sun.star.lang.XServiceInfo</idls>
    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.container.XChild</idls>

    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 <idls>com.sun.star.ucb.XContentCreator</idls>
    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 <idls>com.sun.star.ucb.XContentCreator</idls>

    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.

    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.

    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.

    Creation of New File Contents

    A content representing directories implements the interface <idl>com.sun.star.ucb.XContentCreator</idl>. 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 return 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 <idl>com.sun.star.io.XInputStream</idl> 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

    <idls>com.sun.star.lang.XServiceInfo</idls>

    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.container.XChild</idls>
    <idls>com.sun.star.ucb.XContentCreator</idls>

    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

    <idls>com.sun.star.lang.XServiceInfo</idls>

    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.container.XChild</idls>

    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.

    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.
    Overview of an FTP Content Provider

    Creation of New FTP Content

    FTP accounts and FTP folders implement the interface <idl>com.sun.star.ucb.XContentCreator</idl>. 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 <idl>com.sun.star.io.XInputStream</idl>, 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
    FTPAccount1
    ServerName
    ServerBase2 [readonly] DateCreated
    [readonly] DateModified
    [readonly] FolderCount
    [readonly] DocumentCount

    getCommandInfo

    getPropertySetInfo
    getPropertyValues
    setPropertyValues
    open
    transfer3

    <idls>com.sun.star.lang.XTypeProvider</idls>

    <idls>com.sun.star.lang.XServiceInfo</idls>
    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XContentCreator</idls>

    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
    <idls>com.sun.star.container.XChild</idls>

    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

    <idls>com.sun.star.ucb.XContentCreator</idls>

    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.

    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.

    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.
    WebDav Content Provider

    Creation of New DCP Contents

    DCP folders implement the interface <idl>com.sun.star.ucb.XContentCreator</idl>. 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.

    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:

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

    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

    <idls>com.sun.star.lang.XTypeProvider</idls>

    <idls>com.sun.star.lang.XServiceInfo</idls>
    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.container.XChild</idls>

    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

    <idls>com.sun.star.ucb.XContentCreator</idls>

    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.

    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.
    A Package Content Provider

    Creation of New PCP Contents

    PCP folders implement the interface <idl>com.sun.star.ucb.XContentCreator</idl>. 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 <idl>com.sun.star.io.XInputStream</idl> 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 <idl>com.sun.star.uri.VndSunStarPkgUrlReferenceFactory</idl> 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
    Compressed1

    getCommandInfo

    getPropertySetInfo
    getPropertyValues
    setPropertyValues
    insert
    delete
    open

    <idls>com.sun.star.lang.XTypeProvider</idls>

    <idls>com.sun.star.lang.XServiceInfo</idls>
    <idls>com.sun.star.lang.XComponent</idls>
    <idls>com.sun.star.ucb.XContent</idls>
    <idls>com.sun.star.ucb.XCommandProcessor</idls>
    <idls>com.sun.star.beans.XPropertiesChangeNotifier</idls>
    <idls>com.sun.star.beans.XPropertyContainer</idls>
    <idls>com.sun.star.beans.XPropertySetInfoChangeNotifier</idls>
    <idls>com.sun.star.ucb.XCommandInfoChangeNotifier</idls>
    <idls>com.sun.star.container.XChild</idls>

    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 <idls>com.sun.star.ucb.XContentCreator</idls>

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

    The Help Content Provider

    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.

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

    • 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 <idl>com.sun.star.ucb.XDynamicResultSet</idl>, 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.

    Heckert GNU white.svg

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