summaryrefslogtreecommitdiffstats
path: root/framework/source/inc/loadenv
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--framework/source/inc/loadenv/actionlockguard.hxx144
-rw-r--r--framework/source/inc/loadenv/loadenv.hxx543
-rw-r--r--framework/source/inc/loadenv/loadenvexception.hxx89
-rw-r--r--framework/source/inc/loadenv/targethelper.hxx93
4 files changed, 869 insertions, 0 deletions
diff --git a/framework/source/inc/loadenv/actionlockguard.hxx b/framework/source/inc/loadenv/actionlockguard.hxx
new file mode 100644
index 000000000..417d2d4ed
--- /dev/null
+++ b/framework/source/inc/loadenv/actionlockguard.hxx
@@ -0,0 +1,144 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_ACTIONLOCKGUARD_HXX
+#define INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_ACTIONLOCKGUARD_HXX
+
+#include <com/sun/star/document/XActionLockable.hpp>
+#include <osl/mutex.hxx>
+
+namespace framework{
+
+/** @short implements a guard, which can use the interface
+ <type scope="css::document">XActionLockable</type>.
+
+ @descr This guard should be used to be sure, that any lock will be
+ released. Otherwise the locked document can hinder the office on shutdown!
+*/
+class ActionLockGuard final
+{
+
+ // member
+
+ private:
+ osl::Mutex m_mutex;
+
+ /** @short points to the object, which can be locked from outside. */
+ css::uno::Reference< css::document::XActionLockable > m_xActionLock;
+
+ /** @short knows if a lock exists on the internal lock object
+ forced by this guard instance. */
+ bool m_bActionLocked;
+
+ // interface
+
+ public:
+
+ /** @short default ctor to initialize a "non working guard".
+
+ @descr That can be useful in cases, where no resource still exists,
+ but will be available next time. Then this guard can be used
+ in a mode "use guard for more than one resources".
+ */
+ ActionLockGuard()
+ : m_bActionLocked(false)
+ {
+ }
+
+ /** @short release this guard instance and make sure, that no lock
+ will exist afterwards on the internal wrapped resource.
+ */
+ ~ActionLockGuard()
+ {
+ unlock();
+ }
+
+ /** @short set a new resource for locking at this guard.
+
+ @descr This call will fail, if an internal resource already exists
+ and is currently locked.
+
+ @param xLock
+ points to the outside resource, which should be locked.
+
+ @return sal_True, if new resource could be set and locked.
+ sal_False otherwise.
+ */
+ bool setResource(const css::uno::Reference< css::document::XActionLockable >& xLock)
+ {
+ osl::MutexGuard g(m_mutex);
+
+ if (m_bActionLocked || !xLock.is())
+ return false;
+
+ m_xActionLock = xLock;
+ m_xActionLock->addActionLock();
+ m_bActionLocked = m_xActionLock->isActionLocked();
+
+ return true;
+ }
+
+ /** @short set a new resource for locking at this guard.
+
+ @descr This call will fail, if an internal resource already exists
+ and is currently locked.
+
+ @param xLock
+ points to the outside resource, which should be locked.
+
+ @return sal_True, if new resource could be set and locked.
+ sal_False otherwise.
+ */
+ void freeResource()
+ {
+ // SAFE -> ..........................
+ osl::ClearableMutexGuard aMutexLock(m_mutex);
+
+ css::uno::Reference< css::document::XActionLockable > xLock = m_xActionLock;
+ bool bLocked = m_bActionLocked;
+
+ m_xActionLock.clear();
+ m_bActionLocked = false;
+
+ aMutexLock.clear();
+ // <- SAFE ..........................
+
+ if (bLocked && xLock.is())
+ xLock->removeActionLock();
+ }
+
+ /** @short unlock the internal wrapped resource, if it's not already done. */
+ void unlock()
+ {
+ osl::MutexGuard g(m_mutex);
+ if (m_bActionLocked && m_xActionLock.is())
+ {
+ m_xActionLock->removeActionLock();
+ // don't check for any locks here ...
+ // May another guard use the same lock object :-(
+ m_bActionLocked = false;
+ }
+ }
+};
+
+} // namespace framework
+
+#endif // INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_ACTIONLOCKGUARD_HXX
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/framework/source/inc/loadenv/loadenv.hxx b/framework/source/inc/loadenv/loadenv.hxx
new file mode 100644
index 000000000..9f907e49c
--- /dev/null
+++ b/framework/source/inc/loadenv/loadenv.hxx
@@ -0,0 +1,543 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+#ifndef INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENV_HXX
+#define INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENV_HXX
+
+#include <loadenv/actionlockguard.hxx>
+
+#include <com/sun/star/frame/XComponentLoader.hpp>
+#include <com/sun/star/frame/XFrame.hpp>
+#include <com/sun/star/uno/XComponentContext.hpp>
+#include <com/sun/star/util/URL.hpp>
+#include <rtl/ref.hxx>
+#include <unotools/mediadescriptor.hxx>
+#include <o3tl/typed_flags_set.hxx>
+
+
+/** @short enable/disable special features
+ of a load request.
+
+ @desrc Such features must outcome without
+ any special parameters.
+ To make enabling/disabling of
+ features very easy (e.g. at the ctor of
+ this class) these values must be combinable
+ as flags. That means: its values must be in
+ range of [2^n]!
+ */
+enum class LoadEnvFeatures
+{
+ /// we should be informed, if no feature is enabled :-)
+ NONE = 0,
+ /// enable using of UI elements during loading (means progress, interaction handler etcpp.)
+ WorkWithUI = 1,
+ /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler)
+ AllowContentHandler = 2
+};
+namespace o3tl {
+ template<> struct typed_flags<LoadEnvFeatures> : is_typed_flags<LoadEnvFeatures, 0x3> {};
+}
+
+
+namespace framework {
+
+class QuietInteraction;
+
+/** @short implements general mechanism for loading documents.
+
+ @descr An instance of this class can be used inside the API calls
+ XComponentLoader::loadComponentFromURL() and
+ XDispatch::dispatch().
+ */
+class LoadEnv
+{
+public:
+ /** @short classify a content.
+
+ @descr The load environment must know, if a content
+ is related to a target frame or not. Only "visible"
+ components, which fulfill the requirements of the
+ model-controller-view paradigm can be loaded into a frame.
+ Such contents are classified as E_CAN_BE_LOADED.
+
+ But e.g. for the dispatch framework exists special ContentHandler
+ objects, which can load a content in "non visible" mode ...
+ and do not need a target frame for its operation. Such
+ ContentHandler e.g. plays sounds.
+ Such contents are classified as E_CAN_BE_HANDLED.
+
+ And last but not least a content can be "not valid" in general.
+ */
+ enum EContentType
+ {
+ /// identifies a content, which seems to be invalid in general
+ E_UNSUPPORTED_CONTENT,
+ /// identifies a content, which can be used with a ContentHandler and is not related to a target frame
+ E_CAN_BE_HANDLED,
+ /// identifies a content, which can be loaded into a target frame
+ E_CAN_BE_LOADED,
+ /// special mode for non real loading, In such case the model is given directly!
+ E_CAN_BE_SET
+ };
+
+private:
+ mutable osl::Mutex m_mutex;
+
+ /** @short reference to a uno service manager, which must be used
+ to created on needed services on demand.
+ */
+ css::uno::Reference< css::uno::XComponentContext > m_xContext;
+
+ /** @short points to the frame, which uses this LoadEnv object
+ and must be used to start target search there.
+ */
+ css::uno::Reference< css::frame::XFrame > m_xBaseFrame;
+
+ /** @short points to the frame, into which the new component was loaded.
+
+ @descr Note: This reference will be empty if loading failed
+ or a non visible content was loaded!
+ It can be the same frame as m_xBaseFrame it describe, in case
+ the target "_self", "" or the search flag "SELF" was used.
+ Otherwise it's the new created or recycled frame, which was
+ used for loading and contains further the new component.
+
+ Please use method getTarget() or getTargetComponent()
+ to return the frame/controller or model to any interested
+ user of the results of this load request.
+ */
+ css::uno::Reference< css::frame::XFrame > m_xTargetFrame;
+
+ /** @short contains the name of the target, in which the specified resource
+ of this instance must be loaded.
+ */
+ OUString m_sTarget;
+
+ /** @short if m_sTarget is not a special one, this flags regulate searching
+ of a suitable one.
+ */
+ sal_Int32 m_nSearchFlags;
+
+ /** @short contains all needed information about the resource,
+ which should be loaded.
+
+ @descr Inside this struct e.g. the URL, its type and filter name,
+ the stream or a model directly are saved.
+ */
+ utl::MediaDescriptor m_lMediaDescriptor;
+
+ /** @short because the mediadescriptor contains the complete URL ... but
+ some functionality need the structured version, we hold it twice :-(.
+ */
+ css::util::URL m_aURL;
+
+ /** @short enable/disable special features of a load request. */
+ LoadEnvFeatures m_eFeature;
+
+ /** @short classify the content, which should be loaded by this instance. */
+ EContentType m_eContentType;
+
+ /** @short it indicates, that the member m_xTargetFrame was new created for this
+ load request and must be closed in case loading (not handling!)
+ operation failed. The default value is sal_False!
+ */
+ bool m_bCloseFrameOnError;
+
+ /** @short it indicates, that the old document (which was located inside m_xBaseFrame
+ in combination with the m_sTarget value "_self") was suspended.
+ Normally it will be replaced by the new loaded document. But in case
+ loading (not handling!) failed, it must be reactivated.
+ The default value is sal_False!
+ */
+ bool m_bReactivateControllerOnError;
+
+ /** @short it holds one (!) asynchronous used contenthandler or frameloader
+ alive, till the asynchronous operation will be finished.
+ */
+ css::uno::Reference< css::uno::XInterface > m_xAsynchronousJob;
+
+ /** @short holds the information about the finished load process.
+
+ @descr The content of m_xTargetFrame can't be used as valid indicator,
+ (in case the existing old document was reactivated)
+ we must hold the result of the load process explicitly.
+ */
+ bool m_bLoaded;
+
+ /** @short holds an XActionLock on the internal used task member.
+
+ @seealso m_xTargetFrame
+ */
+ ActionLockGuard m_aTargetLock;
+
+ rtl::Reference<QuietInteraction> m_pQuietInteraction;
+
+public:
+
+ /** @short initialize a new instance of this load environment.
+
+ @param xContext
+ reference to a uno service manager, which can be used internally
+ to create on needed services on demand.
+
+ @throw Currently there is no reason to throw such exception!
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ LoadEnv(const css::uno::Reference< css::uno::XComponentContext >& xContext);
+
+ /** @short deinitialize an instance of this class in the right way.
+ */
+ ~LoadEnv();
+
+ /// @throws css::lang::IllegalArgumentException
+ /// @throws css::io::IOException
+ /// @throws css::uno::RuntimeException
+ static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >& xLoader,
+ const css::uno::Reference< css::uno::XComponentContext >& xContext,
+ const OUString& sURL ,
+ const OUString& sTarget,
+ sal_Int32 nFlags ,
+ const css::uno::Sequence< css::beans::PropertyValue >& lArgs );
+
+ /** @short start loading of a resource
+
+ @descr The parameter for targeting, the content description, and
+ some environment specifier (UI, dispatch functionality)
+ can be set here. Of course a still running load request
+ will be detected here and a suitable exception will be thrown.
+ Such constellation can be detected outside by using provided
+ synchronisation methods or callbacks.
+
+ There is no direct return value possible here. Because it depends
+ from the usage of this instance! E.g. for loading a "visible component"
+ a frame with a controller/model inside can be possible. For loading
+ of a "non visible component" only an information about a successfully start
+ can be provided.
+ Further it can't be guaranteed, that the internal process runs synchronous.
+ that's why we prefer using of specialized methods afterwards e.g. to:
+ - wait till the internal job will be finished
+ and get the results
+ - or to let it run without any further control from outside.
+
+ @param sURL
+ points to the resource, which should be loaded.
+
+ @param lMediaDescriptor
+ contains additional information for the following load request.
+
+ @param xBaseFrame
+ points to the frame which must be used as start point for target search.
+
+ @param sTarget
+ regulate searching/creating of frames, which should contain the
+ new loaded component afterwards.
+
+ @param nSearchFlags
+ regulate searching of targets, if sTarget is not a special one.
+
+ @param eFeature
+ flag field, which enable/disable special features of this
+ new instance for following load call.
+
+ @throw A LoadEnvException e.g. if another load operation is till in progress
+ or initialization of a new one fail by other reasons.
+ The real reason, a suitable message and ID will be given here immediately.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ void startLoading(const OUString& sURL ,
+ const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor,
+ const css::uno::Reference< css::frame::XFrame >& xBaseFrame ,
+ const OUString& sTarget ,
+ sal_Int32 nSearchFlags ,
+ LoadEnvFeatures eFeature = LoadEnvFeatures::NONE);
+
+ /** @short wait for an already running load request (started by calling
+ startLoading() before).
+
+ @descr The timeout parameter can be used to wait some times only
+ or forever. The return value indicates if the load request
+ was finished during the specified timeout period.
+ But it indicates not, if the load request was successful or not!
+
+ @param nTimeout
+ specify a timeout in [ms].
+ A value 0 let it wait forever!
+
+ @return sal_True if the started load process could be finished in time;
+ sal_False if the specified time was over.
+
+ @throw ... currently not used :-)
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ bool waitWhileLoading(sal_uInt32 nTimeout = 0);
+
+ /** TODO document me ... */
+ css::uno::Reference< css::lang::XComponent > getTargetComponent() const;
+
+public:
+
+ /** @short checks if the specified content can be handled by a
+ ContentHandler only and is not related to a target frame,
+ or if it can be loaded by a FrameLoader into a target frame
+ as "visible" component.
+
+ @descr using:
+ switch(classifyContent(...))
+ {
+ case E_CAN_BE_HANDLED :
+ handleIt(...);
+ break;
+
+ case E_CAN_BE_LOADED :
+ xFrame = locateTargetFrame();
+ loadIt(xFrame);
+ break;
+
+ case E_NOT_A_CONTENT :
+ default : throw ...;
+ }
+
+ @param sURL
+ describe the content.
+
+ @param lMediaDescriptor
+ describe the content more detailed!
+
+ @return A suitable enum value, which classify the specified content.
+ */
+ static EContentType classifyContent(const OUString& sURL ,
+ const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor);
+
+ /** TODO document me ... */
+ static void initializeUIDefaults(
+ const css::uno::Reference< css::uno::XComponentContext >& i_rxContext,
+ utl::MediaDescriptor& io_lMediaDescriptor,
+ const bool _bUIMode,
+ rtl::Reference<QuietInteraction>* o_ppQuiteInteraction
+ );
+
+ /** TODO document me ... */
+ void impl_setResult(bool bResult);
+
+ /** TODO document me ... */
+ css::uno::Reference< css::uno::XInterface > impl_searchLoader();
+
+ /** @short it means; show the frame, bring it to front,
+ might set the right icon etcpp. in case loading was
+ successfully or reactivate a might existing old document or
+ close the frame if it was created before in case loading failed.
+
+ @throw A LoadEnvException only in cases, where an internal error indicates,
+ that the complete load environment seems to be not usable in general.
+ In such cases a RuntimeException would be to hard for the outside code :-)
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ void impl_reactForLoadingState();
+
+private:
+ void start();
+
+ /** @short tries to detect the type and the filter of the specified content.
+
+ @descr This method update the available media descriptor of this instance,
+ so it contains the right type, a corresponding filter, may a
+ valid frame loader etc. In case detection failed, this descriptor
+ is corrected first, before a suitable exception will be thrown.
+ (Excepting a RuntimeException occurrence!)
+
+ @attention Not all types we know, are supported by filters. So it does not
+ indicates an error, if no suitable filter(loader etcpp will be found
+ for a type. But a type must be detected for the specified content.
+ Otherwise it's an error and loading can't be finished successfully.
+
+ @throw A LoadEnvException if detection failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ void impl_detectTypeAndFilter();
+
+ /** @short tries to use ContentHandler objects for loading.
+
+ @descr It searches for a suitable content handler object, registered
+ for the detected content type (must be done before by calling
+ impl_detectTypeAndFilter()). Because such handler does not depend
+ from a real target frame, location of such frame will be
+ suppressed here.
+ In case handle failed all new created resources will be
+ removed before a suitable exception is thrown.
+ (Excepting a RuntimeException occurrence!)
+
+ @return TODO
+
+ @throw A LoadEnvException if handling failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ bool impl_handleContent();
+
+ /** @short tries to use FrameLoader objects for loading.
+
+ @descr First the target frame will be located. If it could be found
+ or new created a filter/frame loader will be instantiated and
+ used to load the content into this frame.
+ In case loading failed all new created resources will be
+ removed before a suitable exception is thrown.
+ (Excepting a RuntimeException occurrence!)
+
+ @return TODO
+
+ @throw A LoadEnvException if loading failed.
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ bool impl_loadContent();
+
+ /** @short checks if the specified content is already loaded.
+
+ @descr It depends from the set target information, if such
+ search is allowed or not! So this method checks first,
+ if the target is the special one "_default".
+ If not it returns with an empty result immediately!
+ In case search is allowed, an existing document with the
+ same URL is searched. If it could be found, the corresponding
+ view will get the focus and this method return the corresponding frame.
+ Optional jumpmarks will be accepted here too. So the
+ view of the document will be updated to show the position
+ inside the document, which is related to the jumpmark.
+
+ @return A valid reference to the target frame, which contains the already loaded content
+ and could be activated successfully. An empty reference otherwise.
+
+ @throw A LoadEnvException only in cases, where an internal error indicates,
+ that the complete load environment seems to be not usable in general.
+ In such cases a RuntimeException would be to hard for the outside code :-)
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded();
+
+ /** @short search for any target frame, which seems to be usable
+ for this load request.
+
+ @descr Because this special feature is bound to the target specifier "_default"
+ its checked inside first. If it's not set => this method return an empty
+ reference. Otherwise any currently existing frame will be analyzed, if
+ it can be used here. The following rules exists:
+
+ <ul>
+ <li>The frame must be empty ...</li>
+ <li>or contains an empty document of the same application module
+ which the new document will have (Note: the filter of the new content
+ must be well known here!)</li>
+ <li>and(!) this target must not be already used by any other load request.</li>
+ </ul>
+
+ If a suitable target is located it will be locked. That's why the last rule
+ exists! If this method returns a valid frame reference, it was locked to be usable
+ for this load request only. (Don't forget to reset this state later!)
+ Concurrent LoadEnv instances can synchronize her work be using such locks :-) HOPEFULLY
+
+ @throw A LoadEnvException only in cases, where an internal error indicates,
+ that the complete load environment seems to be not usable in general.
+ In such cases a RuntimeException would be to hard for the outside code :-)
+
+ @throw A RuntimeException in case any internal process indicates, that
+ the whole runtime can't be used any longer.
+ */
+ css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget();
+
+ /** @short because showing of a frame is needed more than once...
+ it's implemented as a separate method .-)
+
+ @descr Note: Showing of a frame is bound to a special feature...
+ a) If we recycle any existing frame, we must bring it to front.
+ Showing of such frame is not needed really... because we recycle
+ visible frames only!
+ b) If the document was already shown (e.g. by our progress implementation)
+ we do nothing here. The reason behind: The document was already shown...
+ and it was already make a top window...
+ If the user activated another frame inbetween (because loading needed some time)
+ it's not allowed to disturb the user again. Then the frame must resists in the background.
+ c) If the frame was not shown before... but loading of a visible document into this frame
+ was finished... we need both actions: setVisible() and toFront().
+
+ @param xWindow
+ points to the container window of a frame.
+
+ @param bForceToFront
+ if it's set to sal_False... showing of the window is done more intelligent.
+ setVisible() is called only if the window was not shown before.
+ This mode is needed by b) and c)
+ If it's set to sal_True... both actions has to be done: setVisible(), toFront()!
+ This mode is needed by a)
+ */
+ void impl_makeFrameWindowVisible(const css::uno::Reference< css::awt::XWindow >& xWindow ,
+ bool bForceToFront);
+
+ /** @short checks whether a frame is already used for another load request or not.
+
+ @descr Such frames can't be used for our "recycle feature"!
+
+ @param xFrame
+ the frame, which should be checked.
+
+ @return [sal_Bool]
+ sal_True if this frame is already used for loading,
+ sal_False otherwise.
+ */
+ bool impl_isFrameAlreadyUsedForLoading(const css::uno::Reference< css::frame::XFrame >& xFrame) const;
+
+ /** @short try to determine the used application module
+ of this load request and apply right position and size
+ for this document window... hopefully before we show it .-)
+ */
+ void impl_applyPersistentWindowState(const css::uno::Reference< css::awt::XWindow >& xWindow);
+
+ /** @short determine if it's allowed to open new document frames.
+ */
+ bool impl_furtherDocsAllowed();
+
+ /** @short jumps to the requested bookmark inside a given document.
+ */
+ void impl_jumpToMark(const css::uno::Reference< css::frame::XFrame >& xFrame,
+ const css::util::URL& aURL );
+
+ /** @short determine if this loader has an interactive dialog shown before
+ loading the document.
+ */
+ bool impl_filterHasInteractiveDialog() const;
+};
+
+} // namespace framework
+
+#endif // INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENV_HXX
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/framework/source/inc/loadenv/loadenvexception.hxx b/framework/source/inc/loadenv/loadenvexception.hxx
new file mode 100644
index 000000000..e4c4eefa6
--- /dev/null
+++ b/framework/source/inc/loadenv/loadenvexception.hxx
@@ -0,0 +1,89 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENVEXCEPTION_HXX
+#define INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENVEXCEPTION_HXX
+
+#include <com/sun/star/uno/Any.hxx>
+
+namespace framework{
+
+/** @short specify an exception, which can be used inside the
+ load environment only.
+
+ @descr Of course outside code must wrap it, to transport
+ the occurred information to its caller.
+ */
+class LoadEnvException
+{
+ public:
+ /** @short Can be used as an ID for an instance of a LoadEnvException.
+ @descr To prevent errors on adding/removing/changing such IDs here,
+ an enum field is used. Its int values are self organized...
+ */
+ enum EIDs
+ {
+ /** @short The specified URL/Stream/etcpp. can not be handled by a LoadEnv instance. */
+ ID_UNSUPPORTED_CONTENT,
+
+ /** @short indicates a corrupted media descriptor.
+ @descr Some parts are required - some other ones are optional. Such exception
+ should be thrown, if a required item does not exists. */
+ ID_INVALID_MEDIADESCRIPTOR,
+
+ /** @short Its similar to a uno::RuntimeException...
+ @descr But such runtime exception can break the whole office code.
+ So its capsulated to this specialized load environment only.
+ Mostly it indicates a missing but needed resource ... e.g the
+ global desktop reference! */
+ ID_INVALID_ENVIRONMENT,
+
+ /** @short indicates a failed search for the right target frame. */
+ ID_NO_TARGET_FOUND,
+
+ /** @short TODO */
+ ID_COULD_NOT_REACTIVATE_CONTROLLER,
+
+ /** @short indicates an already running load operation. Of course the same
+ instance can't be used for multiple load requests at the same time.
+ */
+ ID_STILL_RUNNING,
+
+ /** @short sometimes we can't specify the reason for an error, because we
+ was interrupted by a called code in an unexpected way ...
+ */
+ ID_GENERAL_ERROR
+ };
+
+ sal_Int32 m_nID;
+ OUString m_sMessage;
+ css::uno::Any m_exOriginal;
+
+ LoadEnvException(
+ sal_Int32 id, OUString const & message = OUString(),
+ css::uno::Any const & original = css::uno::Any()):
+ m_nID(id), m_sMessage(message), m_exOriginal(original)
+ {}
+};
+
+} // namespace framework
+
+#endif // INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_LOADENVEXCEPTION_HXX
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/framework/source/inc/loadenv/targethelper.hxx b/framework/source/inc/loadenv/targethelper.hxx
new file mode 100644
index 000000000..046cdfeb1
--- /dev/null
+++ b/framework/source/inc/loadenv/targethelper.hxx
@@ -0,0 +1,93 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_TARGETHELPER_HXX
+#define INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_TARGETHELPER_HXX
+
+#include <rtl/ustring.hxx>
+
+namespace framework{
+
+/** @short can be used to detect, if a target name (used e.g. for XFrame.findFrame())
+ has a special meaning or can be used as normal frame name (e.g. for XFrame.setName()).
+ */
+class TargetHelper
+{
+
+ public:
+
+ /** @short it's used at the following interfaces to classify
+ target names.
+ */
+ enum class ESpecialTarget
+ {
+ Blank,
+ Default,
+ Beamer,
+ HelpTask
+ };
+
+ // interface
+
+ public:
+
+ /** @short it checks the given unknown target name,
+ if it's the expected special one.
+
+ @note An empty target is similar to "_self"!
+
+ @param sCheckTarget
+ must be the unknown target name, which should be checked.
+
+ @param eSpecialTarget
+ represent the expected target.
+
+ @return It returns <TRUE/> if <var>sCheckTarget</var> represent
+ the expected <var>eSpecialTarget</var> value; <FALSE/> otherwise.
+ */
+ static bool matchSpecialTarget(const OUString& sCheckTarget ,
+ ESpecialTarget eSpecialTarget);
+
+ /** @short it checks, if the given name can be used
+ to set it at a frame using XFrame.setName() method.
+
+ @descr Because we handle special targets in a hard coded way
+ (means we do not check the real name of a frame then)
+ such named frames will never be found!
+
+ And in case such special names can exists one times only
+ by definition inside the same frame tree (e.g. _beamer and
+ OFFICE_HELP_TASK) it's not a good idea to allow anything here :-)
+
+ Of course we can't check unknown names, which are not special ones.
+ But we decide, that it's not allowed to use "_" as first sign
+ (because we reserve this letter for our own purposes!)
+ and the value must not a well known special target.
+
+ @param sName
+ the new frame name, which should be checked.
+ */
+ static bool isValidNameForFrame(const OUString& sName);
+};
+
+} // namespace framework
+
+#endif // INCLUDED_FRAMEWORK_SOURCE_INC_LOADENV_TARGETHELPER_HXX
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */