Google Git
Sign in
apache / openoffice-org / refs/heads/services_https / . / content / ucb / docs / ucb-api-usage.html
blob: fad990c485be0ffbb971ca081f929fdd1b14c70d [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<head>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE>How To Use The Universal Content Broker API</TITLE>
<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Win32)">
<META NAME="CREATED" CONTENT="20010110;19410735">
<META NAME="CHANGEDBY" CONTENT="Kai Sommerfeld">
<META NAME="CHANGED" CONTENT="20010511;15364025">
<STYLE>
<!--
A:link { color: #444488 }
A:visited { color: #444488 }
-->
</STYLE>
</head>
<body LINK="#444488" VLINK="#444488">
<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
<COL WIDTH=75>
<TR>
<TD BGCOLOR="#666699">
<H1 ALIGN=CENTER STYLE="margin-top: 0cm; text-decoration: none"><A HREF="http://www.openoffice.org/"><IMG SRC="../images/open_office_org_logo.gif" NAME="Graphic1" ALT="OpenOffice.org" ALIGN=RIGHT WIDTH=126 HEIGHT=53 BORDER=0></A><FONT COLOR="#ffffff"><FONT SIZE=6>How
To Use The Universal Content Broker API</FONT></FONT></H1>
</TD>
</TR>
</TABLE>
<HR SIZE=3 NOSHADE>
<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
<COL WIDTH=256*>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><FONT COLOR="#ffffff"><FONT SIZE=4>Contents</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm"><A HREF="#Abstract">Abstract</A><BR><A HREF="#AccessUCB">Getting
access to the UCB</A><BR><A HREF="#CreateContent">Creating a UCB
Content for a given URL</A><BR><A HREF="#RunCommand">Executing a
command at a UCB Content</A><BR><A HREF="#QueryCommands">Querying
the commands supported by a UCB Content</A><BR><A HREF="#QueryProperties">Querying
the properties supported by a UCB Content</A><BR><A HREF="#GetPropertyValues">Obtaining
property values from a UCB Content</A><BR><A HREF="#SetPropertyValues">Setting
property values of a UCB Content</A><BR><A HREF="#AccessChildren">Accessing
the children of a UCB Folder Content</A><BR><A HREF="#GetDataStream">Accessing
(loading) the content data stream of a UCB Document
Content</A><BR><A HREF="#SetDataStream">Setting (storing) the
content data stream of a UCB Document Content</A><BR><A HREF="#CreateResource">Creating
a new resource</A><BR><A HREF="#DeleteResource">Deleting a
resource</A><BR><A HREF="#TransferResource">Copying, Moving and
Creating links to a resource</A></P>
<P><BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="Abstract"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Abstract</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">This document describes how
software developers can access the functionality of the Universal
Content Broker (UCB). There are code snippets in several sections
that demonstrate the usage of the UCB API, as well as the usage of
the <A HREF="http://www.openoffice.org/source/browse/ucb/ucbhelper/">UCBHELPER</A>
library. That library was designed especially to simplify UCB
usage.</P>
<P STYLE="margin-bottom: 0.1cm">An example for an application that
uses the native UCB API can be found at
<A HREF="http://www.openoffice.org/source/browse/ucb/ucb/workben/ucb/">http://www.openoffice.org/source/browse/ucb/ucb/workben/ucb/</A>.
An application that uses the UCBHELPER library can be found at
<A HREF="http://www.openoffice.org/source/browse/ucb/ucbhelper/workben/ucbexplorer/">http://www.openoffice.org/source/browse/ucb/ucbhelper/workben/ucbexplorer/</A>.
A complete description of the UCB's UNO interfaces and UNO
services can be found in the <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/index.html">UCB
API Reference</A>.</P>
<P ALIGN=LEFT><BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="AccessUCB"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Getting access to the UCB</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm">Before a process can
use the UCB, it needs to do the following steps once:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Create and set the UNO
Service Manager.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Create an instance of the UNO
service &quot;com.sun.star.ucb.UniversalContentBroker&quot;,
passing the keys identifying a predefined UCB configuration.</P>
</UL>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><B>Note:</B> There are
several predefined UCB configurations. Each configuration contains
data that describe a set of UCPs. All UCPs contained in a
configuration will be registered at the UCB that shall be created
using this configuration. A UCB configuration is identified by two
keys, which are strings. The standard configuration is &quot;Local&quot;
and &quot;Office&quot;, which generally allows access to all UCPs.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
bool initUCB()
{
/////////////////////////////////////////////////////////////////////
// Create Process Service Manager. This needs to be done only once
// per process! Afterwards it is accessible via
// comphelper::getProcessServiceFactory().
/////////////////////////////////////////////////////////////////////
uno::Reference&lt; lang::XMultiServiceFactory &gt; xServiceFactory;
try
{
xServiceFactory = cppu::createRegistryServiceFactory(
comphelper::getPathToSystemRegistry(),
rtl::OUString(),
true );
}
catch ( uno::Exception const &amp; ) {}
if ( !xServiceFactory.is() )
return false;
comphelper::setProcessServiceFactory( xServiceFactory );
/////////////////////////////////////////////////////////////////////
// Create UCB. This needs to be done only once per process!
/////////////////////////////////////////////////////////////////////
// Supply configuration to use for this UCB instance...
uno::Sequence&lt; uno::Any &gt; aArgs( 2 );
aArgs[ 0 ] &lt;&lt;= rtl::OUString::createFromAscii( &quot;Local&quot; );
aArgs[ 1 ] &lt;&lt;= rtl::OUString::createFromAscii( &quot;Office&quot; );
uno::Reference&lt; uno::XInterface &gt; xUCB;
try
{
xUCB = xServiceFactory-&gt;createInstanceWithArguments(
rtl::OUString::createFromAscii(
&quot;com.sun.star.ucb.UniversalContentBroker&quot; ),
aArgs );
}
catch ( uno::Exception const &amp; ) {}
if ( !xUCB.is() )
return false;
return true;
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
bool initUCB()
{
/////////////////////////////////////////////////////////////////////
// Create Process Service Manager. This needs to be done only once
// per process! Afterwards it is accessible via
// comphelper::getProcessServiceFactory().
/////////////////////////////////////////////////////////////////////
uno::Reference&lt; lang::XMultiServiceFactory &gt; xServiceFactory;
try
{
xServiceFactory = cppu::createRegistryServiceFactory(
comphelper::getPathToSystemRegistry(),
rtl::OUString(),
true );
}
catch ( uno::Exception const &amp; ) {}
if ( !xServiceFactory.is() )
return false;
comphelper::setProcessServiceFactory( xServiceFactory );
/////////////////////////////////////////////////////////////////////
// Create UCB. This needs to be done only once per process!
/////////////////////////////////////////////////////////////////////
// Supply configuration to use for this UCB instance...
uno::Sequence&lt; uno::Any &gt; aArgs( 2 );
aArgs[ 0 ] &lt;&lt;= rtl::OUString::createFromAscii(
UCB_CONFIGURATION_KEY1_LOCAL );
aArgs[ 1 ] &lt;&lt;= rtl::OUString::createFromAscii(
UCB_CONFIGURATION_KEY2_OFFICE );
return ::ucb::ContentBroker::initialize( xServiceFactory, aArgs );
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="CreateContent"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Creating a UCB Content for a
given URL</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm">Each UCB Content can be
identified using a URL. To create a content object for a given
URL:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Obtain access to the UCB.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the UCB create a content
identifier object for the requested URL
(createContentIdentifier).</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the UCB create a content
object for the just created content identifier object
(queryContent).</P>
<LI><P STYLE="margin-bottom: 0.1cm">The UCB dispatches the
queryContent-call to the appropriate UCP. The UCP will be
selected according to the URL contained in the identifier object.</P>
<LI><P STYLE="margin-bottom: 0.1cm">The UCP creates the content
implementation object.</P>
<LI><P STYLE="margin-bottom: 0.1cm">The UCB returns the content
object returned from the UCP to the original queryContent-caller.</P>
</UL>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
/////////////////////////////////////////////////////////////////////
// Obtain access to UCB...
/////////////////////////////////////////////////////////////////////
uno::Reference&lt; uno::XInterface &gt; xUCB = ...
// Obtain required UCB interfaces...
uno::Reference&lt; ucb::XContentIdentifierFactory &gt; xIdFactory(
xUCB, uno::UNO_QUERY );
if ( !xIdFactory.is() )
... error ...
uno::Reference&lt; ucb::XContentProvider &gt; xProvider(
xUCB, uno::UNO_QUERY );
if ( !xProvider.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Obtain content object from UCB...
/////////////////////////////////////////////////////////////////////
// Create identifier object.
uno::Reference&lt; ucb::XContentIdentifier &gt; xId
= xIdFactory-&gt;createContentIdentifier( rURL );
if ( !xId.is() )
... error ...
uno::Reference&lt; ucb::XContent &gt; xContent
= xProvider-&gt;queryContent( xId );
if ( !xContent.is() )
... error ...
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
rtl::OUString aURL = ...
/////////////////////////////////////////////////////////////////////
// Create an empty content object. ucb::Content::create(...)
// will associate that content with the requested URL...
/////////////////////////////////////////////////////////////////////
::ucb::Content aContent;
bool bSuccess = ::ucb::Content::create(
aURL, uno::Reference&lt; ucb::XCommandEnvironment &gt;(), aContent );
if ( bSuccess )
{
// content is ready for usage now...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="RunCommand"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Executing a command at a UCB
Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">Each UCB Content is able to
execute commands. Once you have created a content object, you can
execute commands at it using its <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XCommandProcessor.html">XCommandProcessor</A>
interface. For a complete list of predefined commands, refer to
the description of the UNO service <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/Content.html">Content</A>.</P>
<P STYLE="margin-bottom: 0.1cm">If executing a command cannot
proceed because of some error condition, the following happens: If
the execute-call was supplied with an <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XCommandEnvironment.html">XCommandEnvironment</A>
that contains an <A HREF="http://api.openoffice.org/common/ref/com/sun/star/task/XInteractionHandler.html">XInteractionHandler</A>,
this interaction handler is used to resolve the problem. If no
interaction handler is supplied (or if it cannot resolve the
problem), an exception describing the error condition is thrown.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Any executeCommand( const uno::Reference&lt; ucb::XContent &gt; &amp; xContent,
const rtl::OUString &amp; rCommandName,
const uno::Any &amp; rArgument )
throw ( ucb::CommandAbortedException, uno::Exception )
{
/////////////////////////////////////////////////////////////////////
// Obtain command processor interface from given content.
/////////////////////////////////////////////////////////////////////
ucb::XCommandProcessor xCmdProcessor( xContent, uno::UNO_QUERY );
/////////////////////////////////////////////////////////////////////
// Assemble command to execute.
/////////////////////////////////////////////////////////////////////
ucb::Command aCommand;
aCommand.Name = rCommandName;
aCommand.Handle = -1; // not available
aCommand.Argument = rArgument;
// Note: throws ucb::CommandAbortedException, uno::Exception
return xCmdProcessor-&gt;execute(
aCommand, 0, uno::Reference&lt; ucb::XCommandEnvironment &gt;() );
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Any executeCommand( const ::ucb::Content &amp; rContent,
const rtl::OUString &amp; rCommandName,
const uno::Any &amp; rArgument )
throw ( ucb::CommandAbortedException, uno::Exception )
{
// Note: throws ucb::CommandAbortedException, uno::Exception
return rContent.executeCommand( rCommandName, rCommandArgument );
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="QueryCommands"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Querying the commands supported
by a UCB Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">Each UCB Content supports the
command <B>getCommandInfo</B>. This command takes a <B>void
argument</B> and returns an implementation of the interface
<A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XCommandInfo.html">XCommandInfo</A>
that can be used to obtain information on the supported commands.
</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Reference&lt; ucb::XCommandInfo &gt; getCommandInfo(
const uno::Reference&lt; ucb::XContent &gt; &amp; xContent )
{
// Execute command &quot;getCommandInfo&quot;.
uno::Reference&lt; ucb::XCommandInfo &gt; xInfo;
try
{
executeCommand( xContent,
rtl::OUString::createFromAscii(
&quot;getCommandInfo&quot; ),
uno::Any() ) &gt;&gt;= xInfo;
{
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
return xInfo;
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Reference&lt; ucb::XCommandInfo &gt; getCommandInfo(
const ::ucb::Content &amp; rContent )
{
uno::Reference&lt; ucb::XCommandInfo &gt; xInfo;
try
{
// UCBHELPER Content has a special method for this command.
xInfo = rContent.getCommands();
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
return xInfo;
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="QueryProperties"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Querying the properties
supported by a UCB Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">Each UCB Content supports the
command <B>getPropertySetInfo</B>. This command takes a <B>void
argument</B> and returns an implementation of the interface
<A HREF="http://api.openoffice.org/common/ref/com/sun/star/beans/XPropertySetInfo.html">XPropertySetInfo</A>
that can be used to obtain information on the supported
properties.
</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Reference&lt; beans::XPropertySetInfo &gt; getPropertySetInfo(
const uno::Reference&lt; ucb::XContent &gt; &amp; xContent )
{
uno::Reference&lt; beans::XPropertySetInfo &gt; xInfo;
try
{
// Execute command &quot;getPropertySetInfo&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii(
&quot;getPropertySetInfo&quot; ),
uno::Any() ) &gt;&gt;= xInfo;
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
return xInfo;
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
uno::Reference&lt; beans::XPropertySetInfo &gt; getPropertySetInfo(
const ::ucb::Content &amp; rContent )
{
uno::Reference&lt; beans::XPropertySetInfo &gt; xInfo;
try
{
// UCBHELPER Content has a special method for this command.
xInfo = rContent.getProperties();
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
return xInfo;
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="GetPropertyValues"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Obtaining property values from
a UCB Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content maintains a set of
properties. It supports the command <B>getPropertyValues</B>,
which can be used to obtain one or more property values from a
content. This command takes an argument of type sequence&lt;
<A HREF="http://api.openoffice.org/common/ref/com/sun/star/beans/Property.html">Property</A>
&gt; and returns an implementation of the interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/sdbc/XRow.html">XRow</A>,
which is very similar to a row of a JDBC resultset. To obtain
property values from a UCB Content:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Define a sequence of
properties for which you want to obtain the values.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the UCB Content execute
the command getPropertyValues.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Obtain the property values
from the returned row object.</P>
</UL>
<P STYLE="margin-bottom: 0.1cm">Note that there are additional
methods available at the Content class of the UCBHELPER library
that can be used to obtain a single property value as uno::Any or
to obtain multiple values as a sequence of uno::Any.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
/////////////////////////////////////////////////////////////////////
// Obtain value of the string property Title and the boolean property
// IsFolder from xContent...
/////////////////////////////////////////////////////////////////////
// Define property sequence.
uno::Sequence&lt; beans::Property &gt; aProps( 2 );
aProps[ 0 ].Name = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 0 ].Handle = -1; // n/a
aProps[ 1 ].Name = rtl::OUString::createFromAscii( &quot;IsFolder&quot; );
aProps[ 1 ].Handle = -1; // n/a
uno::Reference&lt; sdbc::XRow &gt; xValues;
try
{
// Execute command &quot;getPropertyValues&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii(
&quot;getPropertyValues&quot; ),
makeAny( aProps ) ) &gt;&gt;= xValues;
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
if ( !xValues.is() )
... error ...
// Extract values from row object. Note that that the
// first column is 1, not 0.
// Title: Obtain value of column 1 as string.
rtl::OUString aTitle = xValues-&gt;getString( 1 ) );
if ( aTitle.Len() == 0 &amp;&amp; xValues-&gt;wasNull() )
... error ...
// IsFolder: Obtain value of column 2 as boolean.
sal_Bool bFolder = xValues-&gt;getBoolean( 2 );
if ( !bFolder &amp;&amp; xValues-&gt;wasNull() )
... error ...
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2a (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Obtain value of the string property Title and the boolean property
// IsFolder from xContent...
/////////////////////////////////////////////////////////////////////
// Define property sequence.
uno::Sequence&lt; rtl::OUString &gt; aProps( 2 );
aProps[ 0 ] = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 1 ] = rtl::OUString::createFromAscii( &quot;IsFolder&quot; );
uno::Reference&lt; sdbc::XRow &gt; xValues;
try
{
// Obtain property values.
xValues = aContent.getPropertyValuesInterface( aProps );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
// Extract values from row object. Note that that the
// first column is 1, not 0.
// Title: Obtain value of column 1 as string.
rtl::OUString aTitle = xValues-&gt;getString( 1 ) );
if ( aTitle.getLength() == 0 &amp;&amp; xValues-&gt;wasNull() )
... error ...
// IsFolder: Obtain value of column 2 as boolean.
sal_Bool bFolder = xValues-&gt;getBoolean( 2 );
if ( !bFolder &amp;&amp; xValues-&gt;wasNull() )
... error ...
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2b (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Obtain value of the string property Title and the boolean property
// IsFolder from xContent...
/////////////////////////////////////////////////////////////////////
// Define property sequence.
uno::Sequence&lt; rtl::OUString &gt; aProps( 2 );
aProps[ 0 ] = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 1 ] = rtl::OUString::createFromAscii( &quot;IsFolder&quot; );
uno::Sequence&lt; uno::Any &gt; aValues;
try
{
// Obtain property values.
aValues = aContent.getPropertyValues( aProps );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
// Extract values from sequence.
// Title:
rtl::OUString aTitle;
if ( !( aValues[ 0 ] &gt;&gt;= aTitle ) )
... error ...
// IsFolder:
sal_Bool bFolder;
if ( !( aValues[ 1 ] &gt;&gt;= bFolder ) )
... error ...
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="SetPropertyValues"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Setting property values of a
UCB Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content maintains a set of
properties. It supports the command <B>setPropertyValues</B>,
which can be used to set one or more property values of a content.
This command takes an argument of type sequence&lt; <A HREF="http://api.openoffice.org/common/ref/com/sun/star/beans/PropertyValue.html">PropertyValue</A>
&gt; and returns <B>void</B>. To set property values of a UCB
Content:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Define a sequence of property
values you want to set.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the UCB Content execute
the command setPropertyValues.</P>
</UL>
<P STYLE="margin-bottom: 0.1cm">Note that the command will not be
aborted if one or more of the property values cannot be set
(because the requested property is not supported by the content or
because it is read-only). Currently there is no other way to check
whether a property value was set successfully than to obain the
property value after a set-operation. This may change in the near
future, when status information could be returned by the command
setPropertyValues.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
rtl::OUString aNewTitle
= rtl::OUString::createFromAscii( &quot;NewTitle&quot; );
/////////////////////////////////////////////////////////////////////
// Set value of the string property Title...
/////////////////////////////////////////////////////////////////////
// Define property value sequence.
uno::Sequence&lt; beans::PropertyValue &gt; aProps( 1 );
aProps[ 0 ].Name = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 0 ].Handle = -1; // n/a
aProps[ 0 ].Value &lt;&lt;= aNewTitle;
try
{
// Execute command &quot;setPropertyValues&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii(
&quot;setPropertyValues&quot; ),
makeAny( aProps );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2a (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
rtl::OUString aNewTitle
= rtl::OUString::createFromAscii( &quot;NewTitle&quot; );
/////////////////////////////////////////////////////////////////////
// Set value of the string property Title...
/////////////////////////////////////////////////////////////////////
// Define property name sequence.
uno::Sequence&lt; rtl::OUString &gt; aProps( 1 );
aProps[ 0 ] = rtl::OUString::createFromAscii( &quot;Title&quot; );
// Define property value sequence.
uno::Sequence&lt; uno::Any &gt; aValues;
aValues[ 0 ] &lt;&lt;= aNewTitle;
try
{
// Set property values.
aContent.setPropertyValues( aProps, aValues );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2b (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
rtl::OUString aNewTitle
= rtl::OUString::createFromAscii( &quot;NewTitle&quot; );
/////////////////////////////////////////////////////////////////////
// Set value of the string property Title...
/////////////////////////////////////////////////////////////////////
try
{
// Set property value.
aContent.setPropertyValue(
rtl::OUString::createFromAscii( &quot;Title&quot; ),
makeAny( aNewTitle ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="AccessChildren"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Accessing the children of a UCB
Folder Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content that is a folder
(which means that the value of the required property <B>IsFolder</B>
is true) should support the command <B>open</B>. This command
takes an argument of type <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/OpenCommandArgument2.html">OpenCommandArgument2</A>.
The value returned is an implementation of the service
<A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/ContentResultSet.html">ContentResultSet</A>.
This resultset can be understood as a table, where each row
contains a child content of the folder content. You may travel
through the rows by using the resultset's interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/sdbc/XResultSet.html">XResultSet</A>.
The children may be accessed by traveling to the appropriate row
and using the interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XContentAccess.html">XContentAccess</A>,
which is also implemented by the resultset. You may supply a
sequence&lt; <A HREF="http://api.openoffice.org/common/ref/com/sun/star/beans/Property.html">Property</A>
&gt; as part of the argument of the open command. In this case,
the resultset will contain an additional column for each property
value that was requested. You may access the property values by
traveling to the appropriate row and calling methods of the
interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/sdbc/XRow.html">XRow</A>.
There may also other parameters be passed to the open command.
Refer to the documentation of <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/OpenCommandArgument2.html">OpenCommandArgument2</A>
for more information.</P>
<P STYLE="margin-bottom: 0.1cm">To access the children of a UCB
Content:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Fill the OpenCommandArgument2
structure according to your needs.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the UCB Content execute
the command open.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Access the children and the
requested property values using the returned resultset.</P>
</UL>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
/////////////////////////////////////////////////////////////////////
// Open a folder content, request property values for the string
// property Title and the boolean property IsFolder...
/////////////////////////////////////////////////////////////////////
// Fill argument structure...
ucb::OpenCommandArgument2 aArg;
aArg.Mode = ucb::OpenMode::ALL; // FOLDER, DOCUMENTS -&gt; simple filter
aArg.Priority = 32768; // Ignored by most implementations
// Fill info for the properties wanted.
uno::Sequence&lt; beans::Property &gt; aProps( 2 );
aProps[ 0 ].Name = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 0 ].Handle = -1; // n/a
aProps[ 1 ].Name = rtl::OUString::createFromAscii( &quot;IsFolder&quot; );
aProps[ 1 ].Handle = -1; // n/a
aArg.Properties = aProps;
uno::Reference&lt; ucb::XDynamicResultSet &gt; xSet;
try
{
// Execute command &quot;open&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii( &quot;open&quot; ),
makeAny( aArg ) &gt;&gt;= xSet;
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
if ( !xSet.is() )
... error ...
uno::Reference&lt; sdbc::XResultSet &gt; xResultSet(
xSet-&gt;getStaticResultSet() );
if ( !xResultSet.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Iterate over children, access children and property values...
/////////////////////////////////////////////////////////////////////
try
{
// Move to begin.
if ( xResultSet->first() )
{
uno::Reference&lt; ucb::XContentAccess &gt; xContentAccess(
xResultSet, uno::UNO_QUERY );
uno::Reference&lt; sdbc::XRow &gt; xRow(
xResultSet, uno::UNO_QUERY );
do
{
// Obtain URL of child.
rtl::OUString aId
= xContentAccess-&gt;queryContentIdentifierString();
// ucb::XContent xChild
// = xContentAccess-&gt;queryContent();
// First column: Title ( column numbers are 1-based! )
rtl::OUString aTitle = xRow-&gt;getString( 1 );
if ( aTitle.getLength() == 0 &amp;&amp; xRow-&gt;wasNull() )
... error ...
// Second column: IsFolder
sal_Bool bFolder = xRow-&gt;getBoolean( 2 );
if ( !bFolder &amp;&amp; xRow-&gt;wasNull() )
... error ...
}
while ( xResultSet-&gt;next() ) // next child
}
}
catch ( ucb::ResultSetException const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Open a folder content, request property values for the string
// property Title and the boolean property IsFolder...
/////////////////////////////////////////////////////////////////////
// Define property name sequence.
uno::Sequence&lt; OUString &gt; aProps( 2 );
aProps[ 0 ] = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 1 ] = rtl::OUString::createFromAscii( &quot;IsFolder&quot; );
uno::Reference&lt; sdbc::XResultSet &gt; xResultSet;
try
{
xResultSet = aContent.createCursor(
aProps, ::ucb::INCLUDE_FOLDERS_AND_DOCUMENTS );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
if ( !xResultSet.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Iterate over children, access children and property values...
/////////////////////////////////////////////////////////////////////
try
{
// Move to begin.
if ( xResultSet->first() )
{
uno::Reference&lt; ucb::XContentAccess &gt; xContentAccess(
xResultSet, uno::UNO_QUERY );
uno::Reference&lt; sdbc::XRow &gt; xRow(
xResultSet, uno::UNO_QUERY );
do
{
// Obtain URL of child.
rtl::OUString aId
= xContentAccess-&gt;queryContentIdentifierString();
// ucb::XContent xChild
// = xContentAccess-&gt;queryContent();
// First column: Title ( column numbers are 1-based! )
rtl::OUString aTitle = xRow-&gt;getString( 1 );
if ( aTitle.getLength() == 0 &amp;&amp; xRow-&gt;wasNull() )
... error ...
// Second column: IsFolder
sal_Bool bFolder = xRow-&gt;getBoolean( 2 );
if ( !bFolder &amp;&amp; xRow-&gt;wasNull() )
... error ...
}
while ( xResultSet-&gt;next() ) // next child
}
}
catch ( ucb::ResultSetException const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="GetDataStream"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Accessing (loading) the content
data stream of a UCB Document Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content that is a document
(which means that the value of the required property <B>IsDocument</B>
is true) should support the command <B>open</B>. The command takes
an argument of type <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/OpenCommandArgument2.html">OpenCommandArgument2</A>.
Note that this command (with the same argument type) is also used
to access the children of a folder. Whether you get access to the
children or the data stream (or even both, for contents that
support both) is controlled by the argument's <I>Mode</I> member,
as can be seen in the examples. If you are only interested in the
data stream, you can ignore the command's return value (which will
presumably be a null resultset, anyway).</P>
<P STYLE="margin-bottom: 0.1cm">The caller needs to supply the
implementation of a data sink with the arguments in order to get
access to the document's data stream. Generally there are two
different types of data sinks: <A HREF="http://api.openoffice.org/common/ref/com/sun/star/io/XActiveDataSink.html">XActiveDataSink</A>
and <A HREF="http://api.openoffice.org/common/ref/com/sun/star/io/XOutputStream.html">XOutputStream</A>.</P>
<P STYLE="margin-bottom: 0.1cm"><B>XActiveDataSink:</B> If this
type of data sink is supplied, the caller of the command is
active. The implementation of the command will supply an
implementation of the interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/io/XInputStream.html">XInputStream</A>
to the given XActiveDataSink (setInputStream) and return. Once the
execute-call has returned, the caller can access the input stream
(getInputStream) and read the data using that stream (readBytes,
readSomeBytes).</P>
<P STYLE="margin-bottom: 0.1cm"><B>XOutputStream:</B> If this type
of data sink is supplied, the caller of the command is passive.
The implementation of the command will write all data to the
output stream (writeBytes) and close it (closeOutput) after all
data were successfully written. Only then will the open command
return.</P>
<P STYLE="margin-bottom: 0.1cm">Which type to use highly depends
on the logic of the client application. If the application can be
designed so that it passively processes the data supplied by an
XOutputStream, using an XOutputStream as sink is advantageous,
because many content providers can implement this case efficiently
without buffering any data. If, on the other hand, the application
is designed so that it actively reads the data, you should use an
XActiveDataSink; any necessary buffering will then take place in
the implementation of the open command.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
/////////////////////////////////////////////////////////////////////////
// XActiveDataSink interface implementation.
/////////////////////////////////////////////////////////////////////////
class MyActiveDataSink : public cppu::OWeakObject,
public io::XActiveDataSink
{
uno::Reference&lt; io::XInputStream &gt; m_xStream;
public:
// XInterface methods
... queryInterface ... acquire ... release ...
// XActiveDataSink methods.
virtual void SAL_CALL
setInputStream( const uno::Reference&lt; io::XInputStream &gt;&amp; aStream )
throw( uno::RuntimeException )
{ m_xStream = aStream; }
virtual uno::Reference&lt; io::XInputStream &gt; SAL_CALL
getInputStream()
throw( uno::RuntimeException )
{ return m_xStream; }
};
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
/////////////////////////////////////////////////////////////////////
// Read the document data stream of a document content using a
// XActiveDataSink implementation as data sink....
/////////////////////////////////////////////////////////////////////
// Fill argument structure...
ucb::OpenCommandArgument2 aArg;
aArg.Mode = ucb::OpenMode::DOCUMENT;
aArg.Priority = 32768; // Ignored by most implementations
// Create data sink implementation object.
uno::Reference&lt; io::XActiveDataSink &gt; xDataSink
= new MyActiveDataSink;
aArg.Sink = xDataSink;
try
{
// Execute command &quot;open&quot;. The implementation of the command will
// supply an XInputStream implementation to the data sink.
executeCommand( xContent,
rtl::OUString::createFromAscii( &quot;open&quot; ),
makeAny( aArg ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
// Get input stream supplied by the open command implementation.
uno::Reference&lt; io::XInputStream &gt; xData
= xDataSink-&gt;getInputStream();
if ( !xData.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Read data from input stream...
/////////////////////////////////////////////////////////////////////
try
{
// Data buffer. Will be allocated by input stream implementation!
uno::Sequence&lt; sal_Int8 &gt; aBuffer;
sal_Int32 nRead = xData-&gt;readSomeBytes( aBuffer, 65536 );
while ( nRead &gt; 0 )
{
// Process data contained in buffer.
...
nRead = xData-&gt;readSomeBytes( aBuffer, 65536 );
}
// EOF.
}
catch ( io::NotConnectedException const &amp; )
{
... error ...
}
catch ( io::BufferSizeExceededException const &amp; )
{
... error ...
}
catch ( io::IOException const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
/////////////////////////////////////////////////////////////////////////
// XActiveDataSink interface implementation.
/////////////////////////////////////////////////////////////////////////
class MyActiveDataSink : public cppu::OWeakObject,
public io::XActiveDataSink
{
uno::Reference&lt; io::XInputStream &gt; m_xStream;
public:
// XInterface methods
... queryInterface ... acquire ... release ...
// XActiveDataSink methods.
virtual void SAL_CALL
setInputStream( const uno::Reference&lt; io::XInputStream &gt;&amp; aStream )
throw( uno::RuntimeException )
{ m_xStream = aStream; }
virtual uno::Reference&lt; io::XInputStream &gt; SAL_CALL
getInputStream()
throw( uno::RuntimeException )
{ return m_xStream; }
};
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Read the document data stream of a document content using a
// XActiveDataSink implementation as data sink....
/////////////////////////////////////////////////////////////////////
uno::Reference&lt; io::XActiveDataSink &gt; xDataSink
= new MyActiveDataSink;
try
{
aContent.openStream( xDataSink );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
// Get input stream supplied by the open command implementation.
uno::Reference&lt; io::XInputStream &gt; xData
= xDataSink-&gt;getInputStream();
if ( !xData.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Read data from input stream...
/////////////////////////////////////////////////////////////////////
try
{
// Data buffer. Will be allocated by input stream implementation!
uno::Sequence&lt; sal_Int8 &gt; aBuffer;
sal_Int32 nRead = xData-&gt;readSomeBytes( aBuffer, 65536 );
while ( nRead &gt; 0 )
{
// Process data contained in buffer.
...
nRead = xData-&gt;readSomeBytes( aBuffer, 65536 );
}
// EOF.
}
catch ( io::NotConnectedException const &amp; )
{
... error ...
}
catch ( io::BufferSizeExceededException const &amp; )
{
... error ...
}
catch ( io::IOException const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="SetDataStream"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Setting (storing) the content
data stream of a UCB Document Content</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content that is a document
(which means that the value of the required property <B>IsDocument</B>
is true) should support the command <B>insert</B>. This command
can be used to (over)write the document's data stream. The command
requires an argument of type <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/InsertCommandArgument.html">InsertCommandArgument</A>
and returns <B>void</B>. The caller needs to supply the
implementation of an <A HREF="http://api.openoffice.org/common/ref/com/sun/star/io/XInputStream.html">XInputStream</A>
with the command argument. This stream contains the data to be
written. An additional flag indicating whether a possibly existing
content (and its data) shall be overwritten may be supplied with
the command argument. Implementations that are not able to detect
whether there are previous data may ignore this parameter and will
always write the new data!</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
uno::Reference&lt; io::XInputStream &gt; xData = ... // The data to write.
/////////////////////////////////////////////////////////////////////
// Write the document data stream of a document content...
/////////////////////////////////////////////////////////////////////
// Fill argument structure...
ucb::InsertCommandArgument aArg;
aArg.Data = xData;
aArg.ReplaceExisting = true;
try
{
// Execute command &quot;insert&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii( &quot;insert&quot; ),
makeAny( aArg ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
uno::Reference&lt; io::XInputStream &gt; xData = ... // The data to write.
/////////////////////////////////////////////////////////////////////
// Write the document data stream of a document content...
/////////////////////////////////////////////////////////////////////
try
{
aContent.writeStream( xData, true /* replaceexisting */ );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="CreateResource"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Creating a new resource</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">A UCB Content that implements the
interface <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XContentCreator.html">XContentCreator</A>
can act as a factory for new resources. For example, a file system
folder could be a creator for other file system folders and files.</P>
<P STYLE="margin-bottom: 0.1cm">A new content object created by
the XContentCreator implementation can be considered as an <I>empty
hull</I> for a content object of a special type. So this new
content object may need to be filled with some property values in
order to become fully functional. For example, a file system
folder could require a name, which is represented by the property
&quot;Title&quot; in the UCB. The interface XContentCreator offers
ways to determine what contents can be created and what properties
need to be set to get them alive. You may also obtain information
on the general kind (FOLDER, DOCUMENT, LINK) of that objects.
After all required property values are set, the creation process
needs to be committed. This is done using the command <B>insert</B>.
Note that this command is always executed at the new content, not
at the content creator! This is because the creator is not
necessarily the parent of the new content. For a description of
the insert-command refer to section <A HREF="#SetDataStream">Setting
(storing) the content data stream of a UCB Document Content</A>.
One noticeable fact here is that the flag <I>ReplaceExisting</I>
in the insert-command argument usually will be false (the caller
generally does not want to destroy an already existing resource).
The insert-command implementation will make the new content
persistent in the appropriate storage medium.</P>
<P STYLE="margin-bottom: 0.1cm">To create a new resource:</P>
<UL>
<LI><P STYLE="margin-bottom: 0.1cm">Obtain the interface
XContentCreator from a suitable UCB Content.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Call createNewContent at the
content creator. Supply information on the type of content to
create with the arguments.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Obtain and set the property
values that are mandatory for the content just created.</P>
<LI><P STYLE="margin-bottom: 0.1cm">Let the new content execute
the command insert to complete the creation process.</P>
</UL>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
/////////////////////////////////////////////////////////////////////
// Create a new file system file object...
/////////////////////////////////////////////////////////////////////
// Obtain content creator interface.
uno::Reference&lt; XContentCreator &gt; xCreator(
xContent, uno::UNO_QUERY );
if ( !xCreator.is() )
... error ...
// Note: The data for aInfo may have been obtained using
// XContentCreator::queryCreatableContentsInfo().
ucb::ContentInfo aInfo;
aInfo.Type = rtl::OUString::createFromAscii(
&quot;application/vnd.sun.staroffice.fsys-file&quot; );
aInfo.Attributes = 0;
// Create new, empty content.
uno::Reference&lt; ucb::XContent &gt; xNewContent
= xCreator-&gt;createNewContent( aInfo );
if ( !xNewContent.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Set mandatory properties...
/////////////////////////////////////////////////////////////////////
// Obtain a name for the new file.
rtl::OUString aFilename = ...
// Define property value sequence.
uno::Sequence&lt; beans::PropertyValue &gt; aProps( 1 );
aProps[ 0 ].Name = rtl::OUString::createFromAscii( &quot;Title&quot; );
aProps[ 0 ].Handle = -1; // n/a
aProps[ 0 ].Value &lt;&lt;= aFilename;
try
{
// Execute command &quot;setPropertyValues&quot;.
executeCommand( xNewContent,
rtl::OUString::createFromAscii(
&quot;setPropertyValues&quot; ),
makeAny( aProps );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
/////////////////////////////////////////////////////////////////////
// Write the new file to disk...
/////////////////////////////////////////////////////////////////////
// Obtain document data for the new file.
uno::Reference&lt; io::XInputStream &gt; xData = ...
// Fill argument structure...
ucb::InsertCommandArgument aArg;
aArg.Data = xData;
aArg.ReplaceExisting = false;
try
{
// Execute command &quot;insert&quot;.
executeCommand( xNewContent,
rtl::OUString::createFromAscii( &quot;insert&quot; ),
makeAny( aArg ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Create, setup and commit a new file system file object...
/////////////////////////////////////////////////////////////////////
// Obtain a name for the new file.
rtl::OUString aFilename = ...
// Obtain document data for the new file.
uno::Reference&lt; io::XInputStream &gt; xData = ...
uno::Sequence&lt; rtl::OUString &gt; aProps( 1 );
aProps[ 0 ] = rtl::OUString::createFromAscii( &quot;Title&quot; );
uno::Sequence&lt; uno::Any &gt; aValues( 1 );
aValues[ 0 ] &lt;&lt;= aFilename;
::ucb::Content aNewContent;
try
{
aContent.insertNewContent(
rtl::OUString::createFromAscii(
&quot;application/vnd.sun.staroffice.fsys-file&quot; ),
aProps,
aValues,
xData,
aNewContent ); // out parameter!
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="DeleteResource"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Deleting a resource</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">Executing the command <B>delete</B>
on a UCB Content will destroy the resource it represents. This
command takes a boolean parameter. If it is set to <I>true</I>,
the resource will be immediately and physically destroyed. <B>The
command will also destroy all existing sub resources of the
resource to be destroyed! </B>If <I>false</I> is passed to this
command, then the caller only wants to delete the resource
&quot;logically.&quot; This means that the resource can be either
restored or physically destroyed later. A soft-deleted Content
needs to support the command <B>undelete</B>. This command will
bring it back to life. The implementation of the delete command
can ignore the parameter and may opt to always destroy the
resource physically.</P>
<P STYLE="margin-bottom: 0.1cm"><B>Note: Currently we do not have
a Trash Service that could be used by UCB clients to manage
soft-deleted Contents.</B></P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
uno::Reference&lt; ucb::XContent &gt; xContent = ...
/////////////////////////////////////////////////////////////////////
// Destroy a resource physically...
/////////////////////////////////////////////////////////////////////
try
{
sal_Bool bDeletePhysically = sal_True;
// Execute command &quot;delete&quot;.
executeCommand( xContent,
rtl::OUString::createFromAscii( &quot;delete&quot; ),
makeAny( bDeletePhysically ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aContent = ...
/////////////////////////////////////////////////////////////////////
// Destroy a resource physically...
/////////////////////////////////////////////////////////////////////
try
{
sal_Bool bDeletePhysically = sal_True;
// There is no special wrapper method for this simple command.
// Use generic command invocation method.
aContent.executeCommand(
rtl::OUString::createFromAscii( &quot;delete&quot; ),
makeAny( bDeletePhysically ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="TransferResource"></A>
<FONT COLOR="#ffffff"><FONT SIZE=4>Copying, Moving and Creating
links to a resource</FONT></FONT></H3>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<P STYLE="margin-bottom: 0.1cm">Copying, moving and creating links
to a resource works a little differently from the other operations
available for UCB Contents. This is because there are <B>three UCB
Contents</B> involved in these operations (the source object, the
target folder, the target object), not just one. There may even
participation by <B>two Content Providers</B> (e.g., when moving a
file located on an FTP server to the local file system of a
workstation). Each implementation of the <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/UniversalContentBroker.html">UniversalContentBroker</A>
service must support the <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/XCommandProcessor.html">XCommandProcessor</A>
interface. This command processor must implement the command
<B>globalTransfer</B> that can be used to copy and move UCB
Contents and to create links to UCB Contents. The command takes an
argument of type <A HREF="http://api.openoffice.org/common/ref/com/sun/star/ucb/GlobalTransferCommandArgument.html">GlobalTransferCommandArgument</A>.
To copy, move or create a link to a resource simply execute the
globalTransfer command at the UCB.</P>
<P STYLE="margin-bottom: 0.1cm"><B>Note:</B> The reasons for the
different handling are mainly technical. We did not want to force
every single implementation of the transfer command of a UCB
Content to be able to accept (nearly) all types of Contents.
Instead, we wanted to have one single implementation that would be
able to handle all types of Contents. However, the UCBHELPER
library encapsulates this exception and offers a special method
for this functionality at the Content helper class. It must be
called at the UCB Content representing the target folder of the
operation.</P>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
1 (C++)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
rtl::OUString aSourceURL = ... // URL of the source object
rtl::OUString aTargetFolderURL = ... // URL of the target folder
/////////////////////////////////////////////////////////////////////
// Obtain access to UCB...
/////////////////////////////////////////////////////////////////////
uno::Reference&lt; uno::XInterface &gt; xUCB = ...
// Obtain XCommandProcessor interface from UCB...
uno::Reference&lt; ucb::XCommandProcessor &gt; xCmdProc(
xUCB, uno::UNO_QUERY );
if ( !xProcessor.is() )
... error ...
/////////////////////////////////////////////////////////////////////
// Copy a resource to another location...
/////////////////////////////////////////////////////////////////////
try
{
ucb::GlobalTransferCommandArgument aArg;
aArg.TransferCommandOperation = TransferCommandOperation_COPY;
aArg.SourceURL = aSourceURL;
aArg.TargetURL = aTargetFolderURL;
// object keeps it current name
aArg.NewTitle = rtl::OUString();
// fail, if object with same name exists in target folder
aArg.NameClash = NameClash::ERROR;
// Let UCB execute the command &quot;globalTransfer&quot;.
executeCommand( xCmdProc,
rtl::OUString::createFromAscii(
&quot;globalTransfer&quot; ),
makeAny( aArg ) );
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE>
<HR SIZE=1 NOSHADE>
<P ALIGN=LEFT STYLE="margin-bottom: 0.1cm"><FONT SIZE=4><B>Example
2 (C++, using UCBHELPER library)</B></FONT></P>
<HR SIZE=1 NOSHADE>
<PRE>using namespace com::sun::star;
{
::ucb::Content aSourceContent = ... // source content
::ucb::Content aTargetFolderContent = ... // target folder content
/////////////////////////////////////////////////////////////////////
// Copy a resource...
/////////////////////////////////////////////////////////////////////
::ucb::Content aNewContent;
try
{
aTargetFolderContent.insertNewContent(
aSourceContent,
InsertOperation_COPY, // MOVE | LINK
aNewContent ); // out parameter!
}
catch ( ucb::CommandAbortedException const &amp; )
{
... error ...
}
catch ( uno::Exception const &amp; )
{
... error ...
}
}</PRE><P>
<BR>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<HR SIZE=1 NOSHADE>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<HR SIZE=1 NOSHADE>
</TD>
</TR>
<TR>
<TD WIDTH=100% BGCOLOR="#666699">
<P ALIGN=LEFT><FONT COLOR="#ffffff">Author: <A HREF="mailto:kai.sommerfeld@germany.sun.com">Kai
Sommerfeld</A> ($Date: 2002/08/29 10:43:19 $)<BR><I>Copyright 2001
OpenOffice.org Foundation. All Rights Reserved.</I></FONT>
</P>
</TD>
</TR>
<TR>
<TD WIDTH=100%>
<HR SIZE=1 NOSHADE>
</TD>
</TR>
</TABLE>
<HR SIZE=3 NOSHADE>
</body>
</HTML>