Skip to content

Commit

Permalink
Added some doxygen documentation of the OPC interfaces;
Browse files Browse the repository at this point in the history 
git-svn-id: http://frl.googlecode.com/svn/trunk@219 daf5c975-553e-0410-8cda-3135a9dfd8f3
  • Loading branch information
@gmist
gmist committed Feb 14, 2009
1 parent c526d80 commit 36d1a49
Show file tree
Hide file tree
Showing 26 changed files with 6,436 additions and 2,445 deletions.
42 changes: 42 additions & 0 deletions build_tools/doxygen/frl.cfg
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
PROJECT_NAME = "FatRat Library"
OUTPUT_DIRECTORY = "../../output/doc/doxygen"
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = ../../
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.d \
*.java \
*.ii \
*.ixx \
*.ipp \
*.i++ \
*.inl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.idl \
*.odl \
*.cs \
*.php \
*.php3 \
*.inc \
*.m \
*.mm \
*.dox \
*.py \
*.f90 \
*.f \
*.vhd \
*.vhdl
RECURSIVE = YES
QUIET = YES
JAVADOC_AUTOBRIEF = YES
2 changes: 2 additions & 0 deletions build_tools/doxygen/gen.bat
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
mkdir ..\..\output\doc\doxygen
doxygen frl.cfg
113 changes: 63 additions & 50 deletions include/opc/impl/frl_opc_enum_item_attributes.h
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,63 @@
#ifndef frl_opc_enum_item_attributes_h_
#define frl_opc_enum_item_attributes_h_
#include "frl_platform.h"
#if( FRL_PLATFORM == FRL_PLATFORM_WIN32 )
#include <vector>
#include "../dependency/vendors/opc_foundation/opcda.h"
#include "os/win32/com/frl_os_win32_com_allocator.h"
#include "opc/frl_opc_item_attributes.h"

namespace frl{ namespace opc{ namespace impl{

class EnumOPCItemAttributes
: public IEnumOPCItemAttributes,
public os::win32::com::Allocator
{
private:
// reference counter
#if( FRL_COMPILER == FRL_COMPILER_MSVC )
volatile LONG refCount;
#else
LONG refCount;
#endif

std::vector< opc::ItemAttributes > itemList; // attributes array
size_t curIndex; // current element

public:
EnumOPCItemAttributes();
EnumOPCItemAttributes( const EnumOPCItemAttributes& other );
virtual ~EnumOPCItemAttributes();
void addItem( const std::pair< OPCHANDLE, GroupItemElem >& newItem );

// the IUnknown functions
STDMETHODIMP QueryInterface( REFIID iid, LPVOID* ppInterface );
STDMETHODIMP_(ULONG) AddRef( void);
STDMETHODIMP_(ULONG) Release( void);

// the IEnum functions
STDMETHODIMP Next( ULONG celt, OPCITEMATTRIBUTES** rgelt, ULONG* pceltFetched );
STDMETHODIMP Skip ( ULONG celt );
STDMETHODIMP Reset( void );
STDMETHODIMP Clone( IEnumOPCItemAttributes** ppEnum );
}; // class EnumOPCItemAttributes

} // namespace impl
} // namespace opc
} // FatRat Library

#endif // FRL_PLATFORM_WIN32
#endif // frl_opc_enum_item_attributes_h_
#ifndef frl_opc_enum_item_attributes_h_
#define frl_opc_enum_item_attributes_h_
#include "frl_platform.h"
#if( FRL_PLATFORM == FRL_PLATFORM_WIN32 )
#include <vector>
#include "../dependency/vendors/opc_foundation/opcda.h"
#include "os/win32/com/frl_os_win32_com_allocator.h"
#include "opc/frl_opc_item_attributes.h"

namespace frl{ namespace opc{ namespace impl{

/*!
\brief
IEnumOPCItemAttributes implementation.
\details
IEnumOPCItemAttributes allows a client to find out the contents (items) of a group and the attributes of those items.\n
NOTE: most of the returned information was either supplied by or returned to the client at the time it called AddItem.\n
The optional EU information (see the OPCITEMATTRIBUTES discussion) may be very useful to some clients.
This interface is also useful for debugging or for enumerating the contents of a public group.\n
This interface is returned only by IOPCItemMgt::CreateEnumerator. It is not available through query interface.\n
Since enumeration is a standard interface this is described only briefly.\n
See the OLE Programmer's reference for Enumerators for a list and discussion of error codes.
\todo Add OLE Programmer's reference
*/
class EnumOPCItemAttributes
: public IEnumOPCItemAttributes,
public os::win32::com::Allocator
{
private:
// reference counter
#if( FRL_COMPILER == FRL_COMPILER_MSVC )
volatile LONG refCount;
#else
LONG refCount;
#endif

std::vector< opc::ItemAttributes > itemList; // attributes array
size_t curIndex; // current element

public:
EnumOPCItemAttributes();
EnumOPCItemAttributes( const EnumOPCItemAttributes& other );
virtual ~EnumOPCItemAttributes();
void addItem( const std::pair< OPCHANDLE, GroupItemElem >& newItem );

// the IUnknown methods
STDMETHODIMP QueryInterface( REFIID iid, LPVOID* ppInterface );
STDMETHODIMP_(ULONG) AddRef( void);
STDMETHODIMP_(ULONG) Release( void);

// the IEnum methods
STDMETHODIMP Next( ULONG celt, OPCITEMATTRIBUTES** ppItemArray, ULONG* pceltFetched );
STDMETHODIMP Skip ( ULONG celt );
STDMETHODIMP Reset( void );
STDMETHODIMP Clone( IEnumOPCItemAttributes** ppEnumItemAttributes );
}; // class EnumOPCItemAttributes

} // namespace impl
} // namespace opc
} // FatRat Library

#endif // FRL_PLATFORM_WIN32
#endif // frl_opc_enum_item_attributes_h_
214 changes: 140 additions & 74 deletions include/opc/impl/frl_opc_impl_async_io.h
View file
Original file line number Diff line number Diff line change
@@ -1,74 +1,140 @@
#ifndef frl_opc_ipml_async_io_h_
#define frl_opc_ipml_async_io_h_
#include "frl_platform.h"
#if( FRL_PLATFORM == FRL_PLATFORM_WIN32 )
#include "../dependency/vendors/opc_foundation/opcda.h"
#include "opc/frl_opc_group_base.h"

namespace frl { namespace opc { namespace impl {

class AsyncIO
: public IOPCAsyncIO3,
virtual public opc::GroupBase
{
public:
virtual ~AsyncIO();

// IOPCAsyncIO3 implementation
STDMETHODIMP Read(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP Write(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ VARIANT *pItemValues,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP Refresh2(
/* [in] */ OPCDATASOURCE dwSource,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID);

STDMETHODIMP Cancel2(
/* [in] */ DWORD dwCancelID);;

STDMETHODIMP SetEnable(
/* [in] */ BOOL bEnable);

STDMETHODIMP GetEnable(
/* [out] */ BOOL *pbEnable);

STDMETHODIMP ReadMaxAge(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ DWORD *pdwMaxAge,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP WriteVQT(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ OPCITEMVQT *pItemVQT,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP RefreshMaxAge(
/* [in] */ DWORD dwMaxAge,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID);
}; // AsyncIO

} // namespace impl
} // namespace opc
} // FatRat Library

#endif // FRL_PLATFORM_WIN32
#endif // frl_opc_ipml_async_io_h_
#ifndef frl_opc_ipml_async_io_h_
#define frl_opc_ipml_async_io_h_
#include "frl_platform.h"
#if( FRL_PLATFORM == FRL_PLATFORM_WIN32 )
#include "../dependency/vendors/opc_foundation/opcda.h"
#include "opc/frl_opc_group_base.h"

namespace frl { namespace opc { namespace impl {

/*!
\brief
IOPCAsyncIO2 and IOPCAsyncIO3 implementation.
\details
\section IOPCAsyncIO_Details IOPCAsyncIO2
This interface is similar to IOPCAsync. This interface is intended to replace IOPCAsyncIO.
It differs from IOPCAsyncIO as follows:
\arg
It is used to control a connection established with IConnectionPoint rather than IDataObject.
ConnectionPoints have been found to be a much cleaner way to return data than IDataObject.
\arg
Some of the error handling logic is enhanced. Read and Write are allowed to return
additional errors (other than Bad Handle).
\arg
The transaction ID logic has been changed.
The previous (IOPCAsync) implementation did not work well in combination with COM marshalling.
\arg
The async read from cache capability is removed. In practice this was just a slower
and more complex form of a sync read from cache. Server design is simplified by removing this.
IOPCAsyncIO2 allows a client to perform asynchronous read and write operations to a server.
The operations will be "queued" and the function will return immediately so that the client can continue to run.
Each operation is treated as a "transaction" and is associated with a transaction ID.
As the operations are completed, a callback will be made to the IOPCDataCallback in the client.
The information in the callback will indicate the transaction ID and the results of the operation.
Also the expected behavior is that for any one transaction to Async Read, Write and Refresh,
ALL of the results of that transaction will be returned in a single call to appropriate function in IOPCDataCallback.
A server must be able to "queue" at least one transaction of each type (read, write, refresh) for each group.
It is acceptable for a server to return an error (CONNECT_E_ADVISELIMIT)
if more than one transaction of the same type is performed on the same group by the same client.
Server vendors may of course support queueing of additional transactions if they wish.
All operations that are successfully started are expected to complete even if they complete with an error.
The concept of "time-out" is not explicitly addressed in this specification however i
t is expected that where appropriate the server will internally implement
any needed time-out logic and return a server specific error to the caller if this occurs.
<b> Client Implementation Note:</b>
The Unique Transaction ID passed to Read, Write and Refresh is generated by the Client
and is returned to the client in the callback as a way to identify the returned data.
To insure proper client operation, this ID should generally be non-zero
and should be unique to this particular client/server conversation.
It does not need to be unique relative to other conversations by this or other clients.
In any case however the transactionID is completly client specific and must not be checked by the server.
Note that the Group's "Client handle" is also returned in the callback and is generally sufficient to identify the returned data.
<b>IMPORTANT NOTE:</b> depending on the mix of client and server threading models used,
it has been found in practice that the IOPCDataCallback can occur within the same thread as the Refresh, Read or Write
and in fact can occur before the Read, Write or Refresh method returns to the caller.
Thus, if the client wants to save a record of the transaction in some list of
"outstanding transactions" in order to verify completion of a transaction
it will need to generate the Transaction ID and save it BEFORE making the method call.
In practice most clients will probably not need to maintain such a list and so do not actually need to record the transaction ID.
\section IOPCAsyncIO3_Details IOPCAsyncIO3
This interface was added to enhance the existing IOPCAsyncIO2 interface.
IOPCAsyncIO3 inherits from IOPCAsyncIO2 and therefore all IOPCAsyncIO2 methods defined in
IOPCAsyncIO2 are also part of this interface and will not be documented here.
Please refer to the IOPCAsyncIO2 interface methods for further details.
It is expected that Data Access 3.0 only servers, will implement this interface as opposed to IOPCAsyncIO2.
The purpose of this interface is to provide a group level method for asynchronously writing timestamp
and quality information into servers that support this functionality.
In addition, the ability to asynchronously Read from a group based on a "MaxAge" is provided.
This interface differs from the IOPCItemIO interface in that it is asynchronous and group based as opposed to server based.
*/
class AsyncIO
: public IOPCAsyncIO3,
virtual public opc::GroupBase
{
public:
virtual ~AsyncIO();

// IOPCAsyncIO3 implementation
STDMETHODIMP Read(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP Write(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ VARIANT *pItemValues,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP Refresh2(
/* [in] */ OPCDATASOURCE dwSource,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID);

STDMETHODIMP Cancel2(
/* [in] */ DWORD dwCancelID);;

STDMETHODIMP SetEnable(
/* [in] */ BOOL bEnable);

STDMETHODIMP GetEnable(
/* [out] */ BOOL *pbEnable);

STDMETHODIMP ReadMaxAge(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ DWORD *pdwMaxAge,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP WriteVQT(
/* [in] */ DWORD dwCount,
/* [size_is][in] */ OPCHANDLE *phServer,
/* [size_is][in] */ OPCITEMVQT *pItemVQT,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID,
/* [size_is][size_is][out] */ HRESULT **ppErrors);

STDMETHODIMP RefreshMaxAge(
/* [in] */ DWORD dwMaxAge,
/* [in] */ DWORD dwTransactionID,
/* [out] */ DWORD *pdwCancelID);
}; // AsyncIO

} // namespace impl
} // namespace opc
} // FatRat Library

#endif // FRL_PLATFORM_WIN32
#endif // frl_opc_ipml_async_io_h_
8 changes: 8 additions & 0 deletions include/opc/impl/frl_opc_impl_browse.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@

namespace frl { namespace opc { namespace impl {

<<<<<<< .working
=======
/*!
\class BrowseImpl
\brief IOPCBrowse implementation.
\details IOPCBrowse interface provides improved methods for browsing the server address space and for obtaining the item properties.
*/
>>>>>>> .merge-right.r218
class BrowseImpl
: public IOPCBrowse,
virtual public opc::OPCServerBase
Expand Down
Loading

0 comments on commit 36d1a49

Please sign in to comment.