| blob | cfa632aa020fa46d36cef05c127ace63a78c0843 |
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 * This file incorporates work covered by the following license notice:
10 *
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 */
19 #ifndef INCLUDED_UCBHELPER_CONTENT_HXX
20 #define INCLUDED_UCBHELPER_CONTENT_HXX
22 #include <rtl/ref.hxx>
23 #include <com/sun/star/ucb/ContentCreationException.hpp>
24 #include <com/sun/star/ucb/CommandAbortedException.hpp>
25 #include <com/sun/star/io/XStream.hpp>
26 #include <com/sun/star/uno/Reference.hxx>
27 #include <com/sun/star/uno/Sequence.hxx>
28 #include <ucbhelper/ucbhelperdllapi.h>
32 } } } }
38 } } } }
43 } } } }
54 } } } }
58 } } } }
60 namespace ucbhelper
61 {
65 /**
66 * These are the possible values for the parameter eMode of method
67 * ucbhelper::Content::createCursor.
68 */
69 enum ResultSetInclude
70 {
71 INCLUDE_FOLDERS_ONLY,
72 INCLUDE_DOCUMENTS_ONLY,
73 INCLUDE_FOLDERS_AND_DOCUMENTS
74 };
76 /**
77 * These are the possible values for the parameter eOperation of method
78 * ucbhelper::Content::insertNewContent.
79 */
80 enum InsertOperation
81 {
85 InsertOperation_CHECKIN // check-in source data
86 };
92 /**
93 * This class simplifies access to UCB contents by providing a more
94 * convenient API for frequently used functionality then the "raw"
95 * UCB-API does.
96 */
97 class UCBHELPER_DLLPUBLIC Content
98 {
104 ResultSetInclude eMode )
110 /**
111 * Constructor.
112 */
115 /**
116 * Constructor.
117 *
118 * @param rURL is the URL of the content to create.
119 * @param rEnv is the environment to use for commands executed by the
120 * content. The command environment is used by the content
121 * implementation to interact with the client and to propagate
122 * errors.
123 */
131 /**
132 * Constructor.
133 *
134 * @param rContent is the content object of the content to create.
135 * @param rEnv is the environment to use for commands executed by the
136 * content. The command environment is used by the content
137 * implementation to interact with the client and to propagate
138 * errors.
139 */
148 /**
149 * Copy Constructor.
150 *
151 * @param rContent is the content this content shall be a copy of.
152 */
155 /**
156 * Destructor.
157 */
160 /**
161 * Assignment operator.
162 *
163 * @param rContent is the content this content shall be a copy of.
164 */
167 /**
168 * Constructor. This method should be used, if the exception thrown
169 * by the direct ctors of this class are to 'expensive' for your
170 * application
171 *
172 * @param rURL is the URL of the content to create.
173 * @param rEnv is the environment to use for commands executed by the
174 * content. The command environment is used by the content
175 * implementation to interact with the client and to propagate
176 * errors.
177 * @param rContent will be filled by this method with the content created.
178 * @return true, if the operation was successful - false, otherwise.
179 */
180 static bool
189 // Direct access to UCB content.
192 /**
193 * This method provides access to the "native" UCB content interface(s).
194 * This is useful in case the convenience methods provided by this
195 * class are insufficient for your needs. You may obtain all interfaces
196 * supported by the underlying UCB content by calling this method and
197 * after that doing a queryInterface call.
198 *
199 * @return the XContent interface of the underlying UCB content.
200 */
205 // Object identity.
208 /**
209 * This method returns the URL of the content.
210 *
211 * @return the URL of the content.
212 */
216 // Command environment.
219 /**
220 * This method returns the environment to use when executing commands.
221 *
222 * @return the command environment.
223 */
228 /**
229 * This method sets a new command environment.
230 *
231 * @param xNewEnv is the new command environment.
232 */
238 // Access to supported commands/properties.
241 /**
242 * This methods provides access to meta data of the commands supported
243 * by this content.
244 *
245 * @return an XCommandInfo interface implementation, which can be used
246 * to obtain meta data of the commands supported by this content.
247 */
253 /**
254 * This methods provides access to meta data of the properties supported
255 * by this content.
256 *
257 * @return an XPropertSetInfo interface implementation, which can be used
258 * to obtain meta data of the properties supported by this content.
259 */
268 // Access to property value(s).
271 /**
272 * This method can be used to read a single property value.
273 *
274 * @param rPropertyName is the name of the property for that the value
275 * shall be obtained.
276 * @return the property value.
277 */
283 /**
284 * This method can be used to set a single property value.
285 *
286 * @param rPropertyName is the name of the property for that the
287 * value shall be set.
288 * @return an any containing:
289 * - No value indicates, that the property value was set
290 * successfully.
291 * - com::sun::star::beans::UnknownPropertyException indicates,
292 * that the property is not known to the content implementation.
293 * - com::sun::star::beans::IllegalTypeException indicates, that
294 * the data type of the property value is not acceptable.
295 * - com::sun::star::lang::IllegalAccessException indicates, that
296 * the property is constant.
297 * - com::sun::star::lang::IllegalArgumentException indicates,
298 * that the property value is not acceptable. For instance,
299 * setting an empty title may be illegal.
300 * - Any other exception derived from
301 * com::sun::star::uno::Exception indicates, that the value was
302 * not set successfully. For example, this can be a
303 * com::sun:star::ucb::InteractiveAugmentedIOException
304 * transporting the error code
305 * com::sun::star::ucb::IOErrorCode::ACCESS_DENIED.
306 */
313 /**
314 * This method can be used to read multiple property values.
315 *
316 * @param rPropertyNames is a sequence of names of properties for
317 * that the values shall be obtained.
318 * @return the property values.
319 */
326 /**
327 * This method can be used to read multiple property values.
328 *
329 * @param rPropertyNames is a sequence of names of properties for
330 * that the values shall be obtained.
331 * @return the property values.
332 */
340 /**
341 * This method can be used to set multiple property values.
342 *
343 * @param rPropertyNames is a sequence of names of properties for
344 * that values shall be set.
345 * @return a sequence of any's which has exactly the same number
346 * of elements as the number of properties to set. Every
347 * sequence element contains the status for a property. The
348 * first sequence elements corresponds to the first element in
349 * the sequence of property names and so on.
350 *
351 * An any containing:
352 * - No value indicates, that the property value was set
353 * successfully.
354 * - com::sun::star::beans::UnknownPropertyException indicates,
355 * that the property is not known to the content implementation.
356 * - com::sun::star::beans::IllegalTypeException indicates, that
357 * the data type of the property value is not acceptable.
358 * - com::sun::star::lang::IllegalAccessException indicates, that
359 * the property is constant.
360 * - com::sun::star::lang::IllegalArgumentException indicates,
361 * that the property value is not acceptable. For instance,
362 * setting an empty title may be illegal.
363 * - Any other exception derived from
364 * com::sun::star::uno::Exception indicates, that the value was
365 * not set successfully. For example, this can be a
366 * com::sun:star::ucb::InteractiveAugmentedIOException
367 * transporting the error code
368 * com::sun::star::ucb::IOErrorCode::ACCESS_DENIED.
369 */
380 // General command execution.
383 /**
384 * This method can be used to execute any command supported by the
385 * content.
386 *
387 * @param rCommandName is the name of the command to execute.
388 * @param rCommandArgument is the argument for the command. Type and
389 * values of this parameter must correspond to the command
390 * specification.
391 * @return the result of the command according to its specification.
392 */
401 // Special commands.
404 /**
405 * This methods gives access to the children of a folder content.
406 * Additionally, the result set returned provides efficient access to
407 * preselected property values of the children.
408 * Internally it executes the command "open" at the content.
409 *
410 * @param rPropertyNames is a sequence of names of properties for
411 * that the values should be accessible via the resultset
412 * returned by this method.
413 * @param eMode is a very simple filter for the children contained
414 * in the resultset.
415 * @return an implementation of the service
416 * com.cun.star.ucb.ContentResultSet, which can be used to
417 * get access to the children of a content.
418 */
426 /**
427 * This methods gives access to the children of a folder content.
428 * Additionally, the result set returned provides efficient access to
429 * preselected property values of the children.
430 * Internally it executes the command "open" at the content.
431 *
432 * @param rPropertyNames is a sequence of names of properties for
433 * that the values should be accessible via the resultset
434 * returned by this method.
435 * @param eMode is a very simple filter for the children contained
436 * in the resultset.
437 * @return an implementation of the service
438 * com.cun.star.ucb.DynamicResultSet, which can be used to
439 * get access to the children of a content.
440 */
444 ResultSetInclude eMode
453 ::com::sun::star::uno::Reference< ::com::sun::star::ucb::XAnyCompareFactory > rAnyCompareFactory,
459 /**
460 * This methods gives read access to the content stream of a content (i.e
461 * the content of a file located at the local file system).
462 * Internally it executes the command "open" at the content.
463 *
464 * @return an implementation of the interface XInputStream, which can
465 * be used to read the content's data.
466 */
472 /**
473 * This methods gives read access to the content stream of a content (i.e
474 * the content of a file located at the local file system).
475 * Internally it executes the command "open" at the content.
476 * The method requests opening without locking.
477 *
478 * @return an implementation of the interface XInputStream, which can
479 * be used to read the content's data.
480 */
487 /**
488 * This methods gives read/write access to the content stream of a content (i.e
489 * the content of a file located at the local file system).
490 * Internally it executes the command "open" at the content.
491 *
492 * @return an implementation of the interface XStream, which can
493 * be used to read/write the content's data.
494 */
500 /**
501 * This methods gives read/write access to the content stream of a content (i.e
502 * the content of a file located at the local file system).
503 * Internally it executes the command "open" at the content.
504 * The method requests opening without locking.
505 *
506 * @return an implementation of the interface XStream, which can
507 * be used to read/write the content's data.
508 */
515 /**
516 * This methods gives read access to the content stream of a content (i.e
517 * the content of a file located at the local file system).
518 * Internally it executes the command "open" at the content.
519 *
520 * @param rSink is the implementation of an XActiveDataSink interface,
521 * which shall be used by the content to deliver the data.
522 */
523 bool
529 /**
530 * This methods gives read access to the content stream of a content (i.e
531 * the content of a file located at the local file system).
532 * Internally it executes the command "open" at the content.
533 *
534 * @param rStream is the implementation of an XOutputStream interface,
535 * which shall be used by the content to deliver the data.
536 */
537 bool
543 /**
544 * This methods gives write access to the content stream of a content (i.e
545 * the content of a file located at the local file system).
546 * Internally it executes the command "insert" at the content.
547 *
548 * @param rStream is the implementation of an XInputStream interface,
549 * which contains the content data to write.
550 * @param bReplaceExisting specifies, whether any existing content data
551 * shall be overwritten.
552 */
553 void
561 /**
562 * This method returns the different types of contents this content
563 * can create.
564 *
565 * @return the content types or an empty sequence if no contents can be
566 * created by this content.
567 */
574 /**
575 * This method creates, initializes and inserts ( commits ) a new content
576 * (i.e. it could be used to create a new file system folder).
577 * Internally this method does a
578 * XCommandProcessor::execute( "createNewContent", ... );
579 * XCommandProcessor::execute( "setPropertyValues", ... );
580 * XCommandProcessor::execute( "insert", ... ); calling sequence.
581 *
582 * @param rContentType is the type for the new UCB content. Each content
583 * provider implementation may introduce own types for its content
584 * objects (See queryCreatableContentsInfo()).
585 * @param rPropertyNames is a sequence of names of properties for that
586 * values are to set at the new content before it will be inserted
587 * ( committed ).
588 * The order of the names must correspond to the order of the
589 * property values.
590 * @param rPropertyValues is a sequence of property values that are to
591 * set at the new content before it will be inserted ( committed ).
592 * The order of the values must correspond to the order of the
593 * property names.
594 * @param rNewContent will be filled by the implementation of this method
595 * with the new content.
596 */
597 bool
607 /**
608 * This method creates, initializes and inserts (commits) a new content
609 * inside this (the target folder) content. For example, it can be used to
610 * create a new file system file.
611 * Internally this method does a
612 * XCommandProcessor::execute( "createNewContent", ... );
613 * XCommandProcessor::execute( "setPropertyValues", ... );
614 * XCommandProcessor::execute( "insert", ... ); calling sequence.
615 *
616 * @param rContentType is the type for the new UCB content. Each content
617 * provider implementation may introduce own types for its content
618 * objects (See queryCreatableContentsInfo()).
619 * @param rPropertyNames is a sequence of names of properties for that
620 * values are to set at the new content before it will be inserted
621 * ( committed ).
622 * The order of the names must correspond to the order of the
623 * property values.
624 * @param rPropertyValues is a sequence of property values that are to
625 * set at the new content before it will be inserted ( committed ).
626 * The order of the values must correspond to the order of the
627 * property names.
628 * @param rStream is a stream containing the content data for the new
629 * content (i.e. the content of a file to create)
630 * @param rNewContent will be filled by the implementation of this method
631 * with the new content.
632 */
633 bool
646 /**
647 * This method transfers (copies/moves) a content. It creates a new
648 * resource inside this (the target folder) content.
649 * The implementation is able to do cross-provider transfers (like copying
650 * a file from the local file system to a directory located on an HTTP
651 * server).
652 * Internally this method executes the command "globalTransfer" at the UCB.
653 *
654 * @param rSourceContent is the content that contains the data for the
655 * new UCB content.
656 * @param eOperation defines what shall be done with the source data
657 * ( COPY, MOVE, LINK ).
658 * @param rTitle contains a title for the new content. If this is an empty
659 * string, the new content will have the same title as the source
660 * content.
661 * @param rNameClashAction describes how the implementation shall behave
662 * in case a content with a clashing name exists in the target
663 * folder.
664 * NameClash::ERROR will abort the operation, NameClash::OVERWRITE
665 * will overwrite the clashing content and all its data,
666 * NameClash::RENAME will generate and supply a non-clashing title.
667 * @see com/sun/star/ucb/NameClash.idl
668 * @param rMimeType contains the MIME type of the document to write.
669 * @param bMajorVersion tells to create a new major version for checkin operations
670 * @param rCommentVersion contains the comment to use for checkin operations
671 * @param rResultURL is a hacky way to get the update URL after the operation in
672 * case there was a change (introduced for the checkin operation)
673 * @param rDocumentId is the document Id ( in case of CMIS ).
674 */
675 bool
677 InsertOperation eOperation,
690 // Required properties.
693 /**
694 * This method returns the value of the content's property "IsFolder".
695 *
696 * @return true, if the content is a folder ( it can contain other
697 * UCB contents). false, otherwise.
698 */
699 bool
704 /**
705 * This method returns the value of the content's property "IsDocument".
706 *
707 * @return true, if the content is a document ( it has a content stream ).
708 * false, otherwise.
709 */
710 bool
715 };
721 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */