ProCOM Infrastructure

Introduction

ProCOM application is using PROMainDLL.dll as the interfaces factory library. PROMainDLL.dll is providing IProMain interface accessible by calling GetProMainInterface export function. IProMain interface is the interface providing GetInterface method that is the key method for creating instances of other interfaces. GetIProMain inline function defined in inthelpr.h is the common function used for accessing IProMain interface. GetPROInterface inline function is the common function used for creating interfaces instances. Next example shows how to create some instance of some interface:

_com_ptr(ISomeInterface);
if (FAILED(GetPROInterface(IID_ ISomeInterface, (void**)(& ISomeInterface)), 0, 0, pParameters))
     return E_FAIL;

In the example above GetPROInterface inline function will call GetIProMain function to get IProMain interface and then call GetInterface method of this interface to create an instance of the required interface.

It is important to pass 5th argument to GetPROInterface function. This is the PRO parameters – the set of properties stored in the IProperties interface that are including DSN of the connected database and the user ID for this database as well as some other important parameters. When you pass pro parameters to GetPROInterface function – the created interface instance is capable to access correct database with correct user rights and settings taken from pro parameters. Where to get the pro parameters? Pro parameters are passed to any point of the application by the GUI part. If there are no pro parameters – this is the bug and should be fixed.

In many places of the code you can find (and this is the good practice) classes where there is inline member function like in the example below:

inline HRESULT GetPROInterface(REFIID riid, void** ppvObject) const
            { return ::GetPROInterface(riid, ppvObject, m_nSenderType, m_dwSenderID, m_pIProProperties); }

There the class creates a copy of the pro parameters (do not AddFef()) received in the constructor when the class is constructed (example) and then when there is a need for some interface instance next kind of code can be used to get some object:

GetPROInterface(IID_IPROObjectManager, (void**)(&pObjectManager))

This is the correct example of how GetPROInterface function should be used since any instance of any interface received using such a way will get its own proper pro parameters.

Code folders structure

Root structure of the project contains:

1. Common folder is including 2 main folders:
   1. Interfaces contains files with interfaces declaration
   2. Metadata contains objects and parameters declarations
2. Resshare.32 contains libraries used for different applications
3. Utils.32 contains helper applications
4. Webpro.32 contains web application
5. Wellpro.32 contains fieldpro application project and related libraries

All the projects are using U disk to place intermediate output files in debug and V disk to put files in release. You have to make corresponding subst command to enable corresponding disks.

Performance warning: best building code performance is achieved when U and V virtual disks are located on the different to code PHYSICAL disks.

Core interfaces and data types

Most of the interactions between different application parts are performed using standard interfaces for data exchange, they are:

1. IProperties (see ICommonInterfaces.h). Key methods of this interface are GetPropValue and SetPropValue which allow getting and setting VARIANT type value that corresponds to specific PID.
2. IEnumInfo (see ICommonInterfaces.h). This is interface is derived from IProperties and key methods are GetInfo and SetInfo allow getting and setting object type and object key. Therefore IEnumInfo can be treated in some cases are object since it has type, key and a set of properties.
3. IEnumerator (see ICommonInterfaces.h). Key methods of this interface are Reset and Next. Reset method reset internal position identifier to the start. Next method allows to get an instance of IEnumInfo if the return value is success value.

It is recommended to use COleVariantExt VARIANT class wrapper located in OleVariantExt.h. It is recommended to use _com_ptr interface wrapper for handling interfaces.

Do not use classes (including MFC classes) in interfaces declarations.

Principal helper interfaces

1. IPROObjectManager located in ipromain.H. Responsible for getting information about object types and real objects, enumerations of object types and real objects.
2. IParametersManager located in ipromain.H Responsible for getting information about parameters of object types and enumerations of parameters of object types.
3. IChannelManager located in ichannel.h Responsible for getting information about channel types and enumerations of channel types. And also channels creation and information retrieval.

Dynamic libraries

Procom dynamic libraries can provide different functionality such as:

1. Interfaces instances (see the link how to properly declare, implement and use)
2. Actions (see the link how to properly declare, implement and use)
3. Screens (see the link how to properly declare, implement and use)
4. Triggers (see the link how to properly declare, implement and use)
5. Tree loaders (see the link how to properly declare, implement and use)
6. Channels (see the link how to properly declare, implement and use)
7. Archives (see the link how to properly declare, implement and use)

Other important points

• Multilanguage. Any part of GUI communication with the user should use StrTranslate function located in cmnutils.dll. Passing a string value to it should be surrounded by #{} symbols. So that if you need a some message to be translated to currently selected by a user language and traced to system messages then next code should be used as example”

PROTrace(StrTranslate(_T(“${This is some error message}”)), ptfScreen|ptfFile, esmtError);

Although PROTrace function does not need the message to be translated the example below is useful to understand how to make a translation. Note that in the list control and toolbars translation is already implemented. In most of the cases all that you need is to pass a text surrounded with specific symbols. And only if you see in FIP that some part of the program displaying text with surrounding symbols – then you have to check that something is going wrong.

• In a lot of places you need to indicate the progress when performing time consuming operations to avoid user thinking that the program is frozen. In this case if you do not need a user to press cancel button and stop some operation – use IID_IGlobalProgress interface. Usage example is shown below.

_com_ptr(IProgress);
If (SUCCEEDED(::GetProInterface(IID_IGlobalProgress, (void**)&pIProgress)))
{
   pIProgress->SetRange(0, 100);
   pIProgress->SetPos(50);
}

• As indicated above in some cases you have to give a user a message without showing message box. In this cases next function should be used: PROTrace which is located in cmnutils.dll.