[fdo-commits] r711 -
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices
svn_fdo at osgeo.org
svn_fdo at osgeo.org
Thu Feb 1 20:10:41 EST 2007
Author: gregboone
Date: 2007-02-01 20:10:41 -0500 (Thu, 01 Feb 2007)
New Revision: 711
Modified:
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgConnectionManager.h
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgFeatureAccessManager.h
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProvider.h
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderCollection.h
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderNameTokens.h
branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderRegistry.h
Log:
893057: DOC: FDO Managed API Documentation Updates
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgConnectionManager.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgConnectionManager.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgConnectionManager.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -24,6 +24,20 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
+/// \brief
+/// The ConnectionManager class supports dynamic creation of connection objects
+/// given a provider name. Derives from ConnectionManager interface.
+///
+/// \remarks
+/// In order for dynamic creation to work, each dynamic link library, shared library,
+/// or assembly that implements a provider must supply a well-defined entry point function that
+/// takes as input a provider name and returns an IConnection instance. The definition of the
+/// entry point function is language- and platform-dependent. For this release of FDO, the
+/// windows libraries supporting FDO providers will be expected to support the following well-known
+/// unmanaged entry point function, which will create and return an unitialized connection object:
+///
+/// FdoIConnection * CreateConnection();
+///
public __sealed __gc class ConnectionManager : public NAMESPACE_OSGEO_RUNTIME::Disposable, public NAMESPACE_OSGEO_FDO::IConnectionManager
{
public:
@@ -56,8 +70,10 @@
inline FdoConnectionManager* GetImpObj();
+/// \cond DOXYGEN-IGNORE
protected:
System::Void ReleaseUnmanagedObject();
+/// \endcond
};
END_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgFeatureAccessManager.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgFeatureAccessManager.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgFeatureAccessManager.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -26,11 +26,14 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
+/// \brief
+/// The FeatureAccessManager class manages the set of feature providers stored in the FDO provider registry
+/// and provides support for dynamic discovery and binding to registered feature providers
public __sealed __gc class FeatureAccessManager
{
public:
/// \brief
- /// Static method that gets an object that implements IConnection Manager
+ /// Static method that gets an object that implements IConnectionManager
///
/// \return
/// Returns a static instance of an IConnectionManager object.
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProvider.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProvider.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProvider.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -23,7 +23,8 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
/// \brief
-/// Provides information about a feature provider, including name, description, library, and version information.
+/// The Provides class provides information about a feature provider, including name,
+/// description, library, and version information.
public __sealed __gc class Provider : public NAMESPACE_OSGEO_RUNTIME::Disposable
{
public:
@@ -32,7 +33,7 @@
/// [Company].[Provider].[Version].
///
/// \return
- /// Returns the name as a constant wchar_t*.
+ /// Returns the name of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_Name();
@@ -41,7 +42,7 @@
/// Gets a user friendly display name of the feature provider.
///
/// \return
- /// Returns the display name as a constant wchar_t*.
+ /// Returns the display name of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_DisplayName();
@@ -50,7 +51,7 @@
/// Gets a brief description of the feature provider.
///
/// \return
- /// Returns the description as a constant wchar_t*.
+ /// Returns the description of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_Description();
@@ -60,7 +61,7 @@
/// [VersionMajor].[VersionMinor].[BuildMajor].[BuildMinor].
///
/// \return
- /// Returns the version as a constant wchar_t*.
+ /// Returns the version of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_Version();
@@ -70,7 +71,7 @@
/// The version number string has the form [VersionMajor].[VersionMinor].[BuildMajor].[BuildMinor].
///
/// \return
- /// Returns the Feature Data Objects version as a constant wchar_t*.
+ /// Returns the Feature Data Objects version of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_FeatureDataObjectsVersion();
@@ -79,7 +80,7 @@
/// Gets the FULL library path + library name of the provider.
///
/// \return
- /// Returns the library path as a constant wchar_t*.
+ /// Returns the library path of the Provider.
/// Throws an instance of Exception if an error occurs.
///
__property System::String* get_LibraryPath();
@@ -100,8 +101,10 @@
inline FdoProvider* GetImpObj();
+/// \cond DOXYGEN-IGNORE
protected:
System::Void ReleaseUnmanagedObject();
+/// \endcond
};
END_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderCollection.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderCollection.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderCollection.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -27,13 +27,35 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
/// \brief
-/// The ProviderCollection class represents a collection of Provider string.
+/// Class ProviderCollection is a read-only collection consisting of the FDO Providers that are currently registered.
+/// Each collected Provider object describes an installed and registered FDO Feature Provider.
[System::Reflection::DefaultMemberAttribute("RealTypeItem")]
-public __sealed __gc class ProviderCollection : public NAMESPACE_OSGEO_RUNTIME::Disposable, public System::Collections::ICollection, public System::Collections::IEnumerable
+public __sealed __gc class ProviderCollection : public NAMESPACE_OSGEO_RUNTIME::Disposable,
+ public System::Collections::ICollection,
+ public System::Collections::IEnumerable
{
+/// \cond DOXYGEN-IGNORE
private:
/// \brief
- /// nested class defined to provide Enumerator.
+ /// A Nested class defined to provide enumeration of Dictionary elements
+ ///
+ /// Enumerators can be used to read the data in the collection,
+ /// but they cannot be used to modify the underlying collection.
+ ///
+ /// An enumerator remains valid as long as the collection remains unchanged.
+ /// If changes are made to the collection, such as adding, modifying, or deleting
+ /// elements, the enumerator is irrecoverably invalidated and the next call to
+ /// MoveNext or Reset throws an InvalidOperationException. If the collection is
+ /// modified between MoveNext and Current, Current returns the element that it is
+ /// set to, even if the enumerator is already invalidated.
+ ///
+ /// The enumerator does not have exclusive access to the collection; therefore,
+ /// enumerating through a collection is intrinsically not a thread-safe procedure.
+ /// Even when a collection is synchronized, other threads can still modify the
+ /// collection, which causes the enumerator to throw an exception. To guarantee
+ /// thread safety during enumeration, you can either lock the collection during
+ /// the entire enumeration or catch the exceptions resulting from changes made
+ /// by other threads.
///
__gc class Enumerator : public System::Collections::IEnumerator
{
@@ -42,19 +64,61 @@
System::Int32 m_nIdx;
public:
+ /// \brief
+ /// Constructs a new Collection Enumerator
+ ///
+ /// \param elements
+ /// Input The collection to enumerate.
+ ///
Enumerator(ProviderCollection* elements) : m_pCol(elements), m_nIdx(-1)
{
}
- __property System::Object* get_Current();
+ /// \brief
+ /// Retrieves the current object at the enumerator location
+ ///
+ /// \return
+ /// Retuns the current object referenced by the enumerator
+ ///
+ __property System::Object *get_Current();
- System::Boolean MoveNext();
+ /// \brief
+ /// Initially, the enumerator is positioned before the first element in the collection.
+ /// At this position, calling the Current property throws an exception.
+ /// Therefore, you must call the MoveNext method to advance the enumerator
+ /// to the first element of the collection before reading the value of Current.
+ /// If MoveNext passes the end of the collection, the enumerator is positioned
+ /// after the last element in the collection and MoveNext returns false.
+ /// When the enumerator is at this position, subsequent calls to MoveNext also return false.
+ /// If the last call to MoveNext returned false, calling Current throws an exception.
+ /// To set Current to the first element of the collection again, you can call Reset
+ /// followed by MoveNext.
+ ///
+ /// \return
+ /// Retuns true if the Enumerator is able to move to a valid element
+ /// otherwise false.
+ ///
+ System::Boolean MoveNext();
- System::Void Reset();
+ /// \brief
+ /// Initially, the enumerator is positioned before the first element in the collection.
+ /// The Reset method brings the enumerator back to this position.
+ ///
+ System::Void Reset();
};
public private:
+ /// \brief
+ /// Constructs a ProviderCollection managed object based on an unmanaged instance of the object
+ ///
+ /// \param unmanaged
+ /// Input A Pointer to the unmanaged object.
+ ///
+ /// \param autoDelete
+ /// Input Indicates if the constructed object should be automatically deleted
+ /// once it no longer referenced.
+ ///
ProviderCollection(System::IntPtr unmanaged, System::Boolean autoDelete)
: Disposable(unmanaged, autoDelete)
{
@@ -65,13 +129,12 @@
private:
// System::Collections::ICollection interfaces
System::Void System::Collections::ICollection::CopyTo(System::Array* array,System::Int32 index);
-
__property System::Object* System::Collections::ICollection::get_SyncRoot();
-
__property System::Boolean System::Collections::ICollection::get_IsSynchronized();
protected:
System::Void ReleaseUnmanagedObject();
+/// \endcond
public:
/// \brief
@@ -84,8 +147,11 @@
__property System::Int32 get_Count(System::Void);
/// \brief
- /// Gets an enumerator that can iterate through a collection.
+ /// Gets an enumerator that can iterate through a collection.
///
+ /// \return
+ /// Returns an enumerator for the collection.
+ ///
__sealed System::Collections::IEnumerator* GetEnumerator(System::Void);
/// \brief
@@ -115,10 +181,11 @@
System::Int32 IndexOf(System::String* name);
/// \brief
- /// Copies the elements of the collection to an array.
+ /// Copies the elements of the collection to an array.
///
/// \param array
/// Output the one-dimensional Array that is the destination of the elements copied from this collection.
+ ///
/// \param startAt
/// Input an integer that represents the index in array at which copying begins.
///
@@ -131,7 +198,7 @@
/// The index of the provider in the collection. The index is 0 based.
///
/// \return
- /// Returns an instance of an FdoProvider.
+ /// Returns an instance of a Provider.
/// Throws an instance of Exception if the index is out of range or an error occurs.
///
__property NAMESPACE_OSGEO_FDO_CLIENTSERVICES::Provider *get_RealTypeItem(System::Int32 index);
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderNameTokens.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderNameTokens.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderNameTokens.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -25,15 +25,29 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
+/// \brief
+/// Class ProviderNameTokens represents an FDO provider name that has been tokenized into its company, name and version parts.
public __gc class ProviderNameTokens : public NAMESPACE_OSGEO_RUNTIME::Disposable
{
public private:
inline FdoProviderNameTokens* GetImpObj();
+/// \cond DOXYGEN-IGNORE
protected:
System::Void ReleaseUnmanagedObject();
+/// \endcond
public:
+ /// \brief
+ /// Constructs an ProviderNameTokens managed object based on an unmanaged instance of the object
+ ///
+ /// \param unmanaged
+ /// Input A Pointer to the unmanaged object.
+ ///
+ /// \param autoDelete
+ /// Input Indicates if the constructed object should be automatically deleted
+ /// once it no longer referenced.
+ ///
ProviderNameTokens(System::IntPtr unmanaged, System::Boolean autoDelete)
: Disposable(unmanaged, autoDelete)
{
@@ -42,7 +56,7 @@
/// \brief
/// Tokenize a full provider name
/// The name is usually of the form "[Company].[Provider].[Version]",
- /// e.g. "Autodesk.Oracle.3.2".
+ /// e.g. "OSGeo.SDF.3.2".
///
/// \param names
/// Input the provider name to tokenize
@@ -68,8 +82,8 @@
///
/// \return
/// Returns the collection of version number components. For
- /// example, if the full provider name is "Autodesk.Oracle.3.1" then
- /// {2,1} is returned.
+ /// example, if the full provider name is "OSGeo.SDF.3.2" then
+ /// {3,2} is returned.
///
System::Double GetVersionTokens()[];
@@ -78,10 +92,11 @@
///
/// \return
/// Returns the local name ( without company and version ). For
- /// example, if the full provider name is "Autodesk.Oracle.3.1" then
- /// "Oracle" is returned.
+ /// example, if the full provider name is "OSGeo.SDF.3.2" then
+ /// "SDF" is returned.
///
System::String *GetLocalName();
+
private:
static System::String *FdoStringsToStringArray(const FdoStringsP &sa)[];
static System::Double FdoVectorToDoubleArrary(const FdoVectorP &da)[];
Modified: branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderRegistry.h
===================================================================
--- branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderRegistry.h 2007-02-02 01:09:37 UTC (rev 710)
+++ branches/3.2.x/Fdo/Managed/Src/OSGeo/FDO/ClientServices/mgProviderRegistry.h 2007-02-02 01:10:41 UTC (rev 711)
@@ -24,6 +24,12 @@
BEGIN_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
+/// \brief
+/// The ProviderRegistry class supports registering, un-registering, and enumerating
+/// registered feature providers. ProviderRegistry is derived from interface IProviderRegistry.
+///
+/// \note
+/// This is not the MS-Windows registry.
public __gc class ProviderRegistry : public NAMESPACE_OSGEO_RUNTIME::Disposable, public NAMESPACE_OSGEO_FDO::IProviderRegistry
{
public:
@@ -61,12 +67,12 @@
/// Returns nothing. Throws an instance of Exception if an error occurs.
///
System::Void RegisterProvider(String * name,
- String * displayName,
- String * description,
- String * version,
- String * fdoVersion,
- String * libraryPath,
- System::Boolean isManaged);
+ String * displayName,
+ String * description,
+ String * version,
+ String * fdoVersion,
+ String * libraryPath,
+ System::Boolean isManaged);
/// \brief
/// Unregisters the provider with the specified name.
@@ -85,8 +91,10 @@
inline FdoProviderRegistry* GetImpObj();
+/// \cond DOXYGEN-IGNORE
protected:
System::Void ReleaseUnmanagedObject();
+/// \endcond
};
END_NAMESPACE_OSGEO_FDO_CLIENTSERVICES
More information about the fdo-commits
mailing list