Copyright: MPT online developer reference                              Copyright © 2002-2003 Melexis IP Group


Contents

Contents

Application layer

Device Application Specific User Interface layer

Product Specific Functions layer

Communication layer

Other objects

Copyright

Copyright © 2002-2006 Melexis GTS Group. All rights reserved.


Disclaimer

THIS SOFTWARE IS COPYRIGHT BY MELEXIS. ALL RIGHTS RESERVED.

THE SOFTWARE PRODUCT AND ANY RELATED DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OR MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. THE ENTIRE RISK ARISING OUT OF USE OR PERFORMANCE OF THE SOFTWARE PRODUCT REMAINS WITH YOU.

To the maximum extent permitted by applicable law, in no event shall the copyright holder be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the Software.

If the copy of the Software you received was accompanied by a printed or other form of "hard-copy" End User License Agreement whose terms vary from this Agreement, then the hard-copy End User License Agreement governs your use of the Software.

This software is not fault-tolerant and is not designed, manufactured, not intended for use in a system requiring failsafe performance.


Object Model
Object model of MPT Application layer

The following is the object model of the Application layer. It is exposed to other layers only, not externally:

The Application objects:

Object	Represents

MPTFramework	The main object.

DASUIModules	A collection of DASUI modules currently in use.

MPTLog	An object which provides interface for gathering log data.

MPTStorage	An object for saving and restoring of data.

The object hierarchy:

MPTFramework

DASUIModules

MPTLog

MPTStorage (a standalone object)


MPTFramework Object

The MPTFramework object is the topmost object in the object hierarchy of the Application layer.

Properties

DASUIModules

Devices

MainWindow

Name

SoftwareUpdateServices

Methods

CreateFrame

GetVersion

GetVersionStr

Quit


DASUIModules Object

The DASUIModules object implements a collection of references to DASUIModule objects. It derives from MPTCollection object and therefore implements basic collection functionality.

Methods

AddModule

RemoveModule


MPTLog Object

The MPTLog object provides methods for data logging.

Methods

Trace

SystemTrace


MPTStorage Object

The MPTStorage object provides methods for saving and restoring of property data.

Methods

Read

Write


DASUIModules Property

Applies to: MPTFramework object.

Gets the collection of currently loaded DASUIModule objects. It is implemented by DASUIModules object.

Syntax

Visual Basic:

Property DASUIModules as Object

Read only

Borland C++:

HRESULT get_DASUIModules(/*[out, retval]*/ LPDISPATCH* pVal);

Microsoft Visual C++:

HRESULT get_DASUIModules(/*[retval][out]*/ IDispatch** pVal);

Parameters

pVal

Address of IDispatch* pointer variable that receives the interface pointer to the collection. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IDASUIModules (implemented by DASUIModules object) interfaces.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to DASUIModules object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid pointer.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


Devices Property

Applies to: MPTFramework object.

Gets the collection of currently registered MPTDevice objects.

Syntax

Visual Basic:

Property Devices as Object

Read only

Borland C++:

HRESULT get_Devices(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Devices(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IMPTDevices (implemented by MPTDevices object).

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to collection of device objects.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


MainWindow Property

Applies to: MPTFramework object.

Gets the handle of the main window of MPT framework application.

Syntax

Visual Basic:

Property MainWindow as Long

Read only

Borland C++:

HRESULT get_MainWindow(/*[out, retval]*/ unsigned* pVal);

Microsoft Visual C++:

HRESULT get_MainWindow(/*[retval][out]*/ OLE_HANDLE* pVal);

Parameters

pVal

Address of HWND variable that receives the handle of the main window.

Return value

Visual Basic:

A Long representing the handle of the application's main window.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal does not contain a valid value.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


Name Property

Applies to: MPTFramework object.

Gets the name of MPT framework application object.

Syntax

Visual Basic:

Property Name as String

Read only

Borland C++:

HRESULT get_Name(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT get_Name(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of BSTR variable that receives the name of the object. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the name of the object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


SoftwareUpdateServices Property

Applies to: MPTFramework object.

Gets the web update object. It is not yet implemented.

Syntax

Visual Basic:

Property SoftwareUpdateServices as Object

Read only

Borland C++:

HRESULT get_SoftwareUpdateServices(/*[out, retval]*/ LPDISPATCH* pVal);

Microsoft Visual C++:

HRESULT get_SoftwareUpdateServices(/*[retval][out]*/ IDispatch** pVal);

Parameters

pVal

Address of IDispatch* pointer variable that receives the interface pointer to the object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to web update object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid pointer.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


AddModule Method

Applies to: DASUIModules object.

Adds a new DASUIModule to the collection.

Syntax

Visual Basic:

Function AddModule(pVal as Object) as Long

Borland C++:

HRESULT AddModule(/*[in]*/ LPDISPATCH pVal, /*[out,retval]*/ long* plCookie);

Microsoft Visual C++:

HRESULT AddModule(/*[in]*/ IDispatch* pVal, /*[retval][out]*/ long* plCookie);

Parameters

pVal

A pointer to an instance of IDispatch implementation.

plCookie

An address of a long variable receiving a cookie. Each DASUIModule object has an associated cookie which is obtained with a call to AddModule function. If the object has been already registered, this is the value which has been returned from the first invocation of this function.

Return value

Visual Basic:

A Long containing the associated cookie.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully and the object was registered. *plCookie contains a valid cookie.

S_FALSE	The operation completed successfully but the object has been already registered. *plCookie contains the cookie returned when the object was registered for the first time.

Any other error code	The operation failed. *plCookie contains zero.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

RemoveModule


CreateFrame Method

Applies to: MPTFramework object.

DASUI modules call this method to create parent frame windows for their own windows. This is the way to integrate specific UI with the framework environment.

Syntax

Visual Basic:

Function CreateFrame(pDASUI as Object,

                                   strWndCaption as String,

                                   hPrivateMenu as Long,

                                   hContextMenu as Long,

                                   hWndIcon as Long,

                                   lFlags as Long) as Long

Borland C++:

HRESULT CreateFrame(/*[in]*/ LPDISPATCH pDASUI,

                                      /*[in]*/ BSTR strWndCaption,

                                      /*[in]*/ unsigned hPrivateMenu,

                                      /*[in]*/ unsigned hContextMenu,

                                      /*[in]*/ unsigned hWndIcon,

                                      /*[in]*/ long lFlags,

                                      /*[out,retval]*/ unsigned* phFrame);

Microsoft Visual C++:

HRESULT CreateFrame(/*[in]*/ IDispatch* pDASUI,

                                      /*[in]*/ BSTR strWndCaption,

                                      /*[in]*/ OLE_HANDLE hPrivateMenu,

                                      /*[in]*/ OLE_HANDLE hContextMenu,

                                      /*[in]*/ OLE_HANDLE hWndIcon,

                                      /*[in]*/ long lFlags,

                                      /*[retval][out]*/ OLE_HANDLE* phFrame);

Parameters

pDASUI

A reference to DASUI object that needs a frame window. The framework keeps this reference until the window is destroyed.

strWndCaption

A String specifying the caption of the window.

hPrivateMenu

A handle to menu that appears on the main menu bar when the frame is active.

The menu is destroyed with the frame, thus it is not allowed to call DestroyMenu on the handle if CreateFrame succeeds.

hContextMenu

A handle to menu that appears when the user clicks the icon of the frame. It is concatenated with the standard system menu.

The menu is destroyed with the frame, thus it is not allowed to call DestroyMenu on the handle if CreateFrame succeeds.

hWndIcon

A handle to an icon for the frame.

The handle must be valid until the window is destroyed.

lFlags

A long specifying combination of flags for the frame. Refer to DASUIFlags enumeration for the flags that can be used.

phFrame

Address of handle variable that receives the handle of the frame window.

Return value

Visual Basic:

A handle of a parent frame window.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *phFrame contains valid handle.

Any other error code	The operation failed. *phFrame is not valid.

Remarks

Usually this method is called from Activate method.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

ConnectDevice, Activate


GetVersion Method

Applies to: MPTFramework object.

Gets the version of the software implementation of the MPT framework application.

Syntax

Visual Basic:

Sub GetVersion(pMajor As Long, pMinor As Long)

Borland C++:

HRESULT GetVersion(/*[out]*/ long *pMajor, /*[out]*/ long *pMinor);

Microsoft Visual C++:

HRESULT GetVersion(/*[ref][out]*/ long *pMajor, /*[ref][out]*/ long *pMinor);

Parameters

pMajor

Address of a Long variable that receives the major part of the version.

pMinor

Address of a Long variable that receives the minor part of the version.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pMajor and *pMinor contain valid numbers.

Any other error code	The operation failed. *pMajor and *pMinor contain 0.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

GetVersionStr


GetVersionStr Method

Applies to: MPTFramework object.

Gets the version of the software implementation of the MPT framework application as a string.

Syntax

Visual Basic:

Function GetVersionStr() As String

Borland C++:

HRESULT GetVersionStr(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT GetVersionStr(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of a BSTR variable that receives the string with the version. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the version of the module.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

GetVersion


Quit Method

Applies to: MPTFramework object.

Forces MPT framework application to exit.

Syntax

Visual Basic:

Sub Quit()

Borland C++:

HRESULT Quit();

Microsoft Visual C++:

HRESULT Quit();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. The application has started its shutdown procedure.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application


Log Method

Applies to: MPTLog object.

Sends a message to the data logging stream.

Syntax

Visual Basic:

Sub Log(strTxt as String, vSource, [lFlags as Long = 0])

Borland C++:

HRESULT Log(/*[in]*/ BSTR strTxt, /*[in]*/ TVariantInParam vSource, /*[in,def,opt]*/ long lFlags);

Microsoft Visual C++:

HRESULT Log(/*[in]*/ BSTR strTxt, /*[in]*/ VARIANT vSource, /*[defaultvalue][in]*/ long lFlags = 0);

Parameters

strTxt

A String with the log data.

vSource

A VARIANT specifying the object that generates the message. Can be a String, which is the name of the object, or an object reference. In the latter case the object must implement a String property called Name.

lFlags

A long specifying a combination of flags that control the operation. See chapter Logging flags for information about the interpretation of this parameter.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

SystemLog


Read Method

Applies to: MPTStorage object.

Reads a property from a storage.

Syntax

Visual Basic:

Function Read(strPropName as String)

Borland C++:

HRESULT Read(/*[in]*/ BSTR strPropName, /*[out,retval]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT Read(/*[in]*/ BSTR strPropName, /*[retval][out]*/ VARIANT* pVal);

Parameters

strPropName

A String specifying the name of the property.

pVal

Address of VARIANT variable that receives the value of the property.

Return value

Visual Basic:

The value of the property as it is written in the storage.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each object can access for reading and writing its own property bag only. Thus it can use arbitrary names for its properties, because they do not interfere with the names of the rest objects in the storage.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

Write


RemoveModule Method

Applies to: DASUIModules object.

Deletes the specified DASUIModule object from the collection.

Syntax

Visual Basic:

Sub RemoveModule(lCookie as Long)

Borland C++:

HRESULT RemoveModule(/*[in]*/ long lCookie);

Microsoft Visual C++:

HRESULT RemoveModule(/*[in]*/ long lCookie);

Parameters

lCookie

A long which specifies a DASUIModule object cookie.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The operation did not failed, but the specified DASUIModule was not found in the collection.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

AddModule


SystemLog Method

Applies to: MPTLog object.

Sends a message to the system logging stream.

Syntax

Visual Basic:

Sub SystemLog(strTxt as String, [lFlags as Long = 0])

Borland C++:

HRESULT SystemLog(/*[in]*/ BSTR strTxt, /*[in,def,opt]*/ long lFlags);

Microsoft Visual C++:

HRESULT SystemLog(/*[in]*/ BSTR strTxt, /*[defaultvalue][in]*/ long lFlags = 0);

Parameters

strTxt

A String with the log data.

lFlags

A long specifying a combination of flags that control the operation. See chapter Logging flags for information about the interpretation of this parameter.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

Log


Write Method

Applies to: MPTStorage object.

Writes a property to a storage.

Syntax

Visual Basic:

Sub Write(strPropName as String, propVal)

Borland C++:

HRESULT Write(/*[in]*/ BSTR strPropName, /*[in]*/ TVariantInParam propVal);

Microsoft Visual C++:

HRESULT Write(/*[in]*/ BSTR strPropName, /*[in]*/ VARIANT propVal);

Parameters

strPropName

A String specifying the name of the property.

propVal

A VARIANT holding the value of the property.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each object can access for reading and writing its own property bag only. Thus it can use arbitrary names for its properties, because they do not interfere with the property names of the rest objects in the storage.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MPT framework application

See also

Read


DASUIFlags Enumeration

Description

DASUIFlags enumeration defines constants for use with CreateFrame method.

Definition

The following is a list of the DASUIFlags constants

Constant	Description

uiWantCommands	Indicates that the calling module wants to receive command notifications for this window.

uiWantMessages	Indicates that the calling module wants to receive reflected command notification messages for this window.

uiWantUpdateCommands	Indicates that the calling module wants to update the state of its command items for this window.

Multiple flags can be combined with + operator. Additional flags may be added in the future.

Quick Info

Header: Declared in MLXMPT.h.


Logging flags

The behavior of the methods of the MPTLog object can be controlled with the help of a 32-bit parameter. It is divided into several bit fields:

Field	Meaning

Message priority	This priority is compared with the level of particularity specified by the user. Zero in this field specifies the highest priority, and 255 - the lowest priority. If the message priority, as number, is greater than the level of particularity, the message is discarded.

W	The message is a warning if this flag is set.

E	The message is an error if this flag is set.

If both W and E flags are zero, the message is informative.

T	No message type information is displayed if this flag is set.

DT	No date and time information is displayed if this flag is set.

B	The message text will be displayed using a bold font if this flag is set.

BC	The background color field is valid and must be used if this flag is set.

Text color	Specifies the color of the message text.

Background color	Specifies the background color of the message text. BC flag must be set if this field is used.

R	Reserved for future use. Callers must pass zero to ensure compatibility with future implementations.

There are 16 predefined colors that can be used for the color fields:

Color constant	Value

mptclrBlack	0

mptclrMaroon	1

mptclrGreen	2

mptclrOlive	3

mptclrNavy	4

mptclrPurple	5

mptclrTeal	6

mptclrSilver	7

mptclrGray	8

mptclrRed	9

mptclrLime	10

mptclrYellow	11

mptclrBlue	12

mptclrMagenta	13

mptclrCyan	14

mptclrWhite	15

These constants are defined in MLXMPT.h header file.

Developers may use the following constants to set the flags:

Constant	Use to

ltWarning	Set the W field.

ltError	Set the E field.

lfNoType	Set the T field.

lfNoDateTime	Set the DT field.

lfNoDateType	Set both T and DT fields.

lfBold	Set the B field.

lfBkgndColor	Set the BC field.

These constants are defined in MLXMPT.h header file. Multiple constants may be combined by using the bitwise OR operator.

Visual C++ developers may use the following macros to set the color fields:

Macro	Use to

MPTLogClr(x)	Set the value of the text color field. X is the required color.

MPTLogBkgndClr(x)	Set the value of the background color field. X is the required color.

These macros are defined in MLXMPT.h header file.

Samples:

pLog->SystemTrace(bstrMsg, lfBold | MPTLogClr(mptclrBlue));

System informative message with highest priority. The text must be blue and bold, no background color (white background).

pLog->Trace(bstrMsg, varSrc, lfNoDateType | lfWarning);

Data warning message with highest priority. The text must be black, no background color (white background). Date and time information must not be displayed.


Object Model
Object model of DASUI layer

The functionality of each DASUI module must be implemented in a COM server. It can be either an inprocess or an out-of-process server, however inprocess is the preferred choice for better performance. The following is the object model that the server has to expose in order to be considered as a DASUI module:

The DASUI objects:

Object	Represents

DASUIModule	The user interface module.

The object hierarchy:

DASUIModule (creatable with specific ProgID and CLSID)


DASUIModule Object

The DASUIModule object is the single object in the object hierarchy of a DASUI module. It must implement IDASUIModule interface. It is also allowed to expose the properties and methods of IDASUIModule through IDispatch. Note that IMPTDevice interface inherits IMPTRevisionInfo interface and therefore its methods must be implemented too.

Properties

Devices

Name

Type

Visible

Methods

Activate

ConnectDevice

EnableModeless

GetVersionStr

Load

OnExit

Reset

Save

The DASUIModule object must implement at least one product specific category for a DASUI module, declared in MLXMPTGUID.h, in order to be accessible for the MPT framework.


Devices Property

Applies to: DASUIModule object.

Gets the collection of MPTDevice objects used by this module. It is implemented by ObjectCollection object.

Syntax

Visual Basic:

Property Devices as Object

Read only

Borland C++:

HRESULT get_Devices(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Devices(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IObjectCollection (implemented by ObjectCollection object) interfaces.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to ObjectCollection object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module


Name Property

Applies to: DASUIModule object.

Gets the name of the object.

Syntax

Visual Basic:

Property Name as String

Read only

Borland C++:

HRESULT get_Name(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT get_Name(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of BSTR variable that receives the name of the object. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the name of the object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module


Type Property

Applies to: DASUIModule object.

Gets the type of the underlying devices used by this module.

Syntax

Visual Basic:

Property Type as DeviceType

Read only

Borland C++:

HRESULT get_Type(/*[out, retval]*/ DeviceType* pVal);

Microsoft Visual C++:

HRESULT get_Type(/*[retval][out]*/ DeviceType* pVal);

Parameters

pVal

Address of DeviceType variable that receives the type of the device.

Return value

Visual Basic:

A DeviceType representing the type of the underlying devices.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal does not contain a valid value.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module


Visible Property

Applies to: DASUIModule object.

Gets or sets if the UI of the module is visible or hidden.

Syntax

Visual Basic:

Property Visible as Boolean

Read / Write

Borland C++:

HRESULT get_Visible(/*[out, retval]*/ TOLEBOOL* pVal);

HRESULT set_Visible(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_Visible(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_Visible(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives True if the UI is visible, False if it is hidden.

newVal

A Boolean which specifies if the UI must be shown (if it is True) or hidden (if it is False).

Return value

Visual Basic:

A Boolean which is True if the UI is visible or False if it is hidden.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module

See also

EnableModeless


Activate Method

Applies to: DASUIModule object.

MPT framework calls this method to give the module a chance to create and activate its UI. This happens right after the module has accepted the environment in ConnectDevice method.

Syntax

Visual Basic:

Sub Activate(Param)

Borland C++:

HRESULT Activate(/*[in]*/ TVariantInParam Param);

Microsoft Visual C++:

HRESULT Activate(/*[in]*/ VARIANT Param);

Parameters

Param

A VARIANT containing an activation parameter. It can be a simple Boolean, or an array of VARIANTs, one parameter for each object in the chain of activation.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Usually this method calls the framework and creates one or more windows to interact with the user.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.

See also

ConnectDevice, CreateFrame, MPTMustActivateLowerLayers


ConnectDevice Method

Applies to: DASUIModule object.

Attaches a device object to the DASUI object.

Syntax

Visual Basic:

Sub ConnectDevice(pDev as Object)

Borland C++:

HRESULT ConnectDevice(/*[in]*/ LPDISPATCH pDev);

Microsoft Visual C++:

HRESULT ConnectDevice(/*[in]*/ IDispatch* pDev);

Parameters

pDev

A reference to the device object that this module is going to work with.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.

See also

Activate


EnableModeless Method

Applies to: DASUIModule object.

MPT framework calls this method to enable or disable any modeless windows that the module may have created.

Syntax

Visual Basic:

Sub EnableModeless(vbEnable as Boolean)

Borland C++:

HRESULT EnableModeless(/*[in]*/ TOLEBOOL vbEnable);

Microsoft Visual C++:

HRESULT EnableModeless(/*[in]*/ VARIANT_BOOL vbEnable);

Parameters

vbEnable

A Boolean indicating whether to enable (if it is True) or disable (if it is False) the modeless windows.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.

See also

Visible


GetVersionStr Method

Applies to: DASUIModule object.

Gets the version of the software implementation of the DASUI module as a string.

Syntax

Visual Basic:

Function GetVersionStr() As String

Borland C++:

HRESULT GetVersionStr(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT GetVersionStr(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of a BSTR variable that receives the string with the version of the module. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the version of the module.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module

See also

MPTRevisionInfo


Load Method

Applies to: DASUIModule object.

Initializes the UI object from a storage.

Syntax

Visual Basic:

Sub Load(pStorage as Object)

Borland C++:

HRESULT Load(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Load(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.

See also

Save


OnExit Method

Applies to: DASUIModule object.

MPT framework calls this method when the module is no longer needed. The module must destroy all of its windows, free resources and uninitialize the underlying device objects.

Syntax

Visual Basic:

Sub OnExit()

Borland C++:

HRESULT OnExit();

Microsoft Visual C++:

HRESULT OnExit();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.


Reset Method

Applies to: DASUIModule object.

MPT framework calls this method to initialize the module and the underlying objects.

Syntax

Visual Basic:

Sub Reset()

Borland C++:

HRESULT Reset();

Microsoft Visual C++:

HRESULT Reset();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.


Save Method

Applies to: DASUIModule object.

Stores UI object settings in the storage object.

Syntax

Visual Basic:

Sub Save(pStorage as Object)

Borland C++:

HRESULT Save(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Save(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in DASUI module.

See also

Load


UpdateCommandFlags Enumeration

Description

UpdateCommandFlags enumeration defines constants for use with OnUpdateCommand method.

Definition

The following is a list of the UpdateCommandFlags constants

Constant	Description

ucSetCheck	Indicates that the item must be checked, if present. Otherwise the item must be unchecked.

ucSetText	If present, indicates that the method has changed the text of the item and the framework must update the text. Otherwise the text remains unchanged.

ucDisable	Indicates that the item must be disabled, if present. Otherwise the item must be enabled.

Multiple flags can be combined with + operator. Additional flags may be added in the future.

Quick Info

Header: Declared in MLXMPT.h.


Object Model
Object model of Product Specific Functions layer

The functionality of each PSF module must be implemented in a COM server. It can be either an inprocess or an out-of-process server, however inprocess is the preferred choice for better performance. The following is the object model that the server has to expose in order to be considered as a PSF module:

The PSF objects:

Object	Represents

PSFManager	The main object.

MPTDevice	One or more objects that implement IMPTDevice interface.

The object hierarchy:

PSFManager (creatable with specific ProgID and CLSID)

MPTDevice (creatable with specific ProgID and CLSID)


PSFManager Object

The PSFManager object is the topmost object in the object hierarchy of a product specific functions module. It must implement IPSFManager interface either directly or by implementing a derived interface. It is also allowed to expose the properties and methods of IPSFManager through IDispatch.

Properties

Name

SupportedDevices

Methods

GetModuleVersion

GetModuleVersionStr

ScanStandalone

The PSFManager object must implement at least one of the categories CATID_MLXMPTPSFSerialModule, CATID_MLXMPTPSFParallelModule or CATID_MLXMPTPSFUSBModule, declared in MLXMPTGUID.h, in order to be accessible for the MPT framework.


MPTDevice Object

The MPTDevice object exposes functionality for accessing the underlying physical device. It must implement IMPTDevice interface either directly or by implementing a derived interface. Note that IMPTDevice interface inherits IMPTRevisionInfo interface and therefore its methods must be implemented too.

Properties

Channel

Connected

HasUI

Manager

Name

Parent

Methods

Acquire

Activate

CheckSetup

ConnectChannel

ConnectUI

Destroy

Free

Load

OnMessage

Reset

Save

Uninit

The MPTDevice object must implement at least one of the categories CATID_MLXMPTPSFSerialDevice, CATID_MLXMPTPSFParallelDevice or CATID_MLXMPTPSFUSBDevice, declared in MLXMPTGUID.h, in order to be accessible for the MPT framework. It must also declare a specific required category for a user interface module from the DASUI layer.


Channel Property

Applies to: MPTDevice object.

Gets or sets the associated communication channel.

Syntax

Visual Basic:

Property Channel as Object

Read / Write

Borland C++:

HRESULT get_Channel(/*[out,retval]*/ LPDISPATCH* ppVal);

HRESULT set_Channel(/*[in]*/ LPDISPATCH newVal);

Microsoft Visual C++:

HRESULT get_Channel(/*[retval][out]*/ IDispatch** ppVal);

HRESULT put_Channel(/*[in]*/ IDispatch* newVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the associated channel object. If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

newVal

A pointer to an instance of IDispatch implementation of a channel object. This method internally calls IUnknown::AddRef() on the pointer.

Return value

Visual Basic:

An Object representing the associated channel.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


Connected Property

Applies to: MPTDevice object.

Gets or sets whether the object is connected to its physical device.

Syntax

Visual Basic:

Property Connected as Boolean

Read / Write

Borland C++:

HRESULT get_Connected(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_Connected(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_Connected(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_Connected(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the connection (True - connected, False - not).

newVal

A Boolean specifying the new state of the connection - True forces the object to make an attempt to connect, False - to disconnect.

Return value

Visual Basic:

A Boolean representing current state of the connection (True - connected, False - not).

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal is valid.

Any other error code	The operation failed. *pVal is not valid.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


HasUI Property

Applies to: MPTDevice object.

Gets or sets whether the object is connected a corresponding DASUI object.

Syntax

Visual Basic:

Property HasUI as Boolean

Read / Write

Borland C++:

HRESULT get_HasUI(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_HasUI(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_HasUI(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_HasUI(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the property.

newVal

A Boolean specifying the new state of the property.

Return value

Visual Basic:

A Boolean representing current state of the property.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal is valid.

Any other error code	The operation failed. *pVal is not valid.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


Manager Property

Applies to: MPTDevice object.

Gets a reference to the PSFManager object of the module.

Syntax

Visual Basic:

Property Manager as Object

Read only

Borland C++:

HRESULT get_Manager(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Manager(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to an object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


Name Property

Applies to: PSFManager object, MPTDevice object.

Gets the name of the corresponding object.

Syntax

Visual Basic:

Property Name as String

Read only

Borland C++:

HRESULT get_Name(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT get_Name(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of BSTR variable that receives the name of the object. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the name of the object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


Parent Property

Applies to: MPTDevice object.

Gets the parent devices collection. This is the MPTDevices collection object.

Syntax

Visual Basic:

Property Parent as Object

Read only

Borland C++:

HRESULT get_Parent(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Parent(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the parent object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to an object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


SupportedDevices Property

Applies to: PSFManager object.

The meaning of this property is not yet defined. It is reserved for future use. Current implementors should return E_NOTIMPL.

Syntax

Visual Basic:

Property SupportedDevices as Variant

Read only

Borland C++:

HRESULT get_SupportedDevices(/*[out,retval]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT get_SupportedDevices(/*[retval][out]*/ VARIANT* pVal);

Parameters

pVal

The meaning of this parameter is not yet defined.

Return value

Visual Basic:

Not yet defined.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module


Acquire Method

Applies to: MPTDevice object.

Ensures an exclusive access to the device. Usually this method performs the following sequence:

Channel.LockChannel

if(setBusy)

    Channel.Busy = True

Connected = True

where Channel is the channel object associated with this device object.

This method is provided to speed up the performance.

Syntax

Visual Basic:

Sub Acquire([setBusy as Boolean = False])

Borland C++:

HRESULT Acquire(/*[in,def,opt]*/ TOLEBOOL setBusy);

Microsoft Visual C++:

HRESULT Acquire(/*[defaultvalue][in]*/ VARIANT_BOOL setBusy = VARIANT_FALSE);

Parameters

setBusy

A Boolean indicating whether to set the busy flag of the channel. True sets the busy flag, False does nothing (does not clear the busy flag). Optional, default value is False.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Free


Activate Method

Applies to: MPTDevice object.

Performs final initialization routines and puts the device object into 'ready for work' state.

Syntax

Visual Basic:

Sub Activate(Param)

Borland C++:

HRESULT Activate(/*[in]*/ TVariantInParam Param);

Microsoft Visual C++:

HRESULT Activate(/*[in]*/ VARIANT Param);

Parameters

Param

A VARIANT containing an activation parameter. It can be a simple Boolean, or an array of VARIANTs, one parameter for each object in the chain of activation.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

MPTMustActivateLowerLayers


CheckSetup Method

Applies to: MPTDevice object.

This method checks if the environment is supported by this object. This usually includes checking of communication channel validity, hardware revisions and specific parameters, software revisions as well as setting device specific parameters.

Syntax

Visual Basic:

Sub CheckSetup(bQuiet As Boolean)

Borland C++:

HRESULT CheckSetup(/*[in]*/ TOLEBOOL bQuiet);

Microsoft Visual C++:

HRESULT CheckSetup(/* [in] */ VARIANT_BOOL bQuiet);

Parameters

bQuiet

A Boolean specifying whether error or warning messages will be shown (True) or not (False).

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Following is an algorithm for a typical high-level method implemented in the PSF module.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.


ConnectChannel Method

Applies to: MPTDevice object.

Creates a new channel object and connects it to this device object.

Syntax

Visual Basic:

Sub ConnectChannel(Param, dt As DeviceType)

Borland C++:

HRESULT ConnectChannel(/*[in]*/ TVariantInParam Param,

                                        /*[in]*/ DeviceType dt);

Microsoft Visual C++:

HRESULT ConnectChannel(/* [in] */ VARIANT Param,

                                        /* [in] */ DeviceType dt);

Parameters

Param

Initialization data for the channel. It's value is interpreted depending on the ct parameter:

Channel type	Value of Param

Serial	Can be a string, like "COM1" or an integer number, representing the serial port, taken from the SerialPortNumber enumeration.

Parallel	The meaning of this parameter is not yet defined.

USB	The meaning of this parameter is not yet defined.

IrDA	A string which identifies the name of the device to connect to.

dt

A value from the ChannelType enumeration which specifies the type of the channel to be created. This must be a single channel type, a combination of types is not allowed.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.


ConnectUI Method

Applies to: MPTDevice object.

Connects an UI object to this device object. This method searches the system for a compatible UI class. For every class found, it creates a new DASUI object and calls its ConnectDevice and Activate methods. The process is repeated until the first UI object is found, whose creation and activation methods succeed.

Syntax

Visual Basic:

Sub ConnectUI()

Borland C++:

HRESULT ConnectUI();

Microsoft Visual C++:

HRESULT ConnectUI();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.


Destroy Method

Applies to: MPTDevice object.

Tells the device object to free all of its resources and prepare for destruction.

Syntax

Visual Basic:

Sub Destroy(Flag as Boolean)

Borland C++:

HRESULT Destroy(/*[in]*/ TOLEBOOL Flag);

Microsoft Visual C++:

HRESULT Destroy(/*[in]*/ VARIANT_BOOL Flag);

Parameters

Flag

A Boolean specifying the action to perform:

Value	Action

False	Release the associated channel object. MPT framework uses this value.

True	Unregister from the devices collection with a call to UnregisterDevice. Device objects created with ScanStandalone procedure should be destroyed in this manner. If necessary, UnregisterDevice will call internally Destroy(False) on the device object.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.


Free Method

Applies to: MPTDevice object.

Release a lock on the device. Usually this method performs the following sequence:

if(clearBusy)

    Channel.Busy = False

Channel.UnlockChannel

where Channel is the channel object associated with this device object.

This method is provided to speed up the performance.

Syntax

Visual Basic:

Sub Free([clearBusy as Boolean = False])

Borland C++:

HRESULT Free(/*[in,def,opt]*/ TOLEBOOL clearBusy);

Microsoft Visual C++:

HRESULT Free(/*[defaultvalue][in]*/ VARIANT_BOOL clearBusy = VARIANT_FALSE);

Parameters

clearBusy

A Boolean indicating whether to clear the busy flag of the channel. True clears the busy flag, False does nothing. Optional, default value is False.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Acquire


GetModuleVersion Method

Applies to: PSFManager object.

Gets the version of the software implementation of the PSF module.

Syntax

Visual Basic:

Sub GetModuleVersion(pMajor As Long, pMinor As Long)

Borland C++:

HRESULT GetModuleVersion(/*[out]*/ long *pMajor, /*[out]*/ long *pMinor);

Microsoft Visual C++:

HRESULT GetModuleVersion(/*[ref][out]*/ long *pMajor, /*[ref][out]*/ long *pMinor);

Parameters

pMajor

Address of a Long variable that receives the major part of the version of the module.

pMinor

Address of a Long variable that receives the minor part of the version of the module.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pMajor and *pMinor contain valid numbers.

Any other error code	The operation failed. *pMajor and *pMinor contain 0.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module

See also

GetModuleVersionStr


GetModuleVersionStr Method

Applies to: PSFManager object.

Gets the version of the software implementation of the PSF module as a string.

Syntax

Visual Basic:

Function GetModuleVersionStr() As String

Borland C++:

HRESULT GetModuleVersionStr(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT GetModuleVersionStr(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of a BSTR variable that receives the string with the version of the module. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the version of the module.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module

See also

GetModuleVersion


Load Method

Applies to: MPTDevice object.

Initializes the device object from a storage.

Syntax

Visual Basic:

Sub Load(pStorage as Object)

Borland C++:

HRESULT Load(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Load(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Save


OnMessage Method

Applies to: MPTDevice object.

This method is called by DispatchDeviceMessage method of the underlying channel.

Syntax

Visual Basic:

Sub OnMessage(lMessage as Long, args, pSender as Object)

Borland C++:

HRESULT OnMessage(/*[in]*/ long lMessage,

                                    /*[in]*/ TVariantInParam args,

                                    /*[in]*/ LPDISPATCH pSender);

Microsoft Visual C++:

HRESULT OnMessage(/*[in]*/ long lMessage,

                                    /*[in]*/ VARIANT args,

                                    /*[in]*/ IDispatch* pSender);

Parameters

lMessage

A long identifying the message.

args

A VARIANT providing additional message data.

pSender

A pointer to an instance of IDispatch implementation. This is the object that has emitted the message.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module

See also

DispatchDeviceMessage


Reset Method

Applies to: MPTDevice object.

Initializes the device object and eventually the physical device. They both should be ready for work if this method returns successfully.

Syntax

Visual Basic:

Sub Reset([Param])

Borland C++:

HRESULT Reset(/*[in]*/ TVariantInParam Param);

Microsoft Visual C++:

HRESULT Reset(/*[optional][in]*/ VARIANT Param);

Parameters

Param

A VARIANT providing device dependent initialization parameter. The meaning of this value should be explained in each implementation and, if used, may modify the behavior of the method.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Uninit


Save Method

Applies to: MPTDevice object.

Stores device object settings in the storage object.

Syntax

Visual Basic:

Sub Save(pStorage as Object)

Borland C++:

HRESULT Save(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Save(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Load


ScanStandalone Method

Applies to: PSFManager object.

Scans the system for supported devices. If a device is found, it should be provided with a MPTDevice object.

The method returns an ObjectCollection object holding references to the newly created device objects.

Syntax

Visual Basic:

Function ScanStandalone(dt as DeviceType, [Devices]) as Object

Borland C++:

HRESULT ScanStandalone(/*[in]*/ DeviceType dt,

                                           /*[in,opt]*/ TVariantInParam Devices,

                                           /*[out,retval]*/ LPDISPATCH* pDevicesArray);

Microsoft Visual C++:

HRESULT ScanStandalone(/*[in]*/ DeviceType dt,

                                           /*[optional][in]*/ VARIANT Devices,

                                           /*[retval][out]*/ IDispatch** pDevicesArray);

Parameters

dt

A value from the DeviceType enumeration, which specifies the type of devices of interest. Multiple flags can be combined by using the bitwise OR operator.

Devices

A String or an array of strings which specify PSF device object categories. They identify devices to scan for. Optional. If omitted, ScanStandalone searches for all devices, which have an associated PSF device object in the same PSF module.

pDevicesArray

Address of IDispatch* pointer variable that receives the interface pointer to the collection object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IObjectCollection (implemented by ObjectCollection object) interfaces.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A collection of newly created device objects.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pDevicesArray contains a valid value.

Any other error code	The operation failed.

Remarks

This method is called by stand alone clients of the module, which are not running with MPT framework.

The caller is responsible to call Destroy(True) on the returned device objects when they are no longer needed. Releasing of the collection object does not call Destroy.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also


Uninit Method

Applies to: MPTDevice object.

Puts the physical device in inactive state. This may include switching off the power supply of the device. In most cases this method does nothing.

Syntax

Visual Basic:

Sub Uninit()

Borland C++:

HRESULT Uninit();

Microsoft Visual C++:

HRESULT Uninit();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.

See also

Reset


Object Model
Object model of communication layer

The whole functionality of the communication layer is implemented in an inprocess COM server. The following is the object model of the server:

The CommUnit objects:

Object	Represents

CommManager	The main object.

MPTChannels	A collection of the channels currently in use.

MPTDevices	A collection of the registered devices.

MPTChannel	A base object, defining common channel functionality.

SerialChannel	A channel object for serial communication (derives from MPTChannel).

IrDAChannel	A channel object for IrDA communication (derives from MPTChannel).

PacketOperation	An object, which allows a set of operations to be treated and executed as a single one.

The object hierarchy:

CommManager (creatable with ProgID "MPT.CommManager" or CLSID_CommManager)

MPTChannels

MPTChannel (represented by SerialChannel, IrDAChannel, ParallelChannel (still not implemented) and USBChannel (still not implemented)

MPTDevices

MPTDevice (implemented in upper layers)

PacketOperation (a standalone object)


CommManager Object

The CommManager object is the topmost object in the object hierarchy of the communication module.

Properties

Channels

Devices

Name

Methods

GetVersion

GetVersionStr

Quit


MPTChannels Object

The MPTChannels object represents a collection of currently activated channels. It derives from MPTCollection object and therefore implements basic collection functionality.

Properties

Manager

Methods

CreateChannel

EnumChannels

EnumChannelsStr

FindChannel

ChannelsCanBeCreated


MPTChannel Object

The MPTChannel object defines basic channel functionality. It cannot be created directly, however each channel object can be casted safely to MPTChannel.

MPTChannel is also used to represent a channel regardless of its type.

Properties

BufferSize

Busy

BytesInBuffer

Connected

Devices

DispatchMessages

HashValue

LastError

LocalEcho

Locked

Logging

Manager

Name

Parent

Remote

SendDelay

Status

Timeout

Type

Methods

Activate

AttachDevice

CancelOperation

CreatePacketOperation

Delay

DelayAsync

DetachDevice

DispatchDeviceMessage

Flush

Load

LockChannel

MLXCommand

MLXCommandAsync

MLXReceive

MLXReceiveAsync

ModifyCustomCounter

ReadBuffer

ReadCustomProperty

Receive

ReceiveAsync

ReceiveUntil

ReceiveUntilAsync

Save

Send

SendAsync

Synchronize

UnlockChannel

WriteCustomProperty

Events

OnDelayComplete

OnDestroy

OnError

OnPacketOperationComplete

OnReceivePacket

OnSendComplete

OnSettingsChanged


MPTDevices Object

The MPTDevices object represents a collection of currently registered devices. It derives from MPTCollection object and therefore implements basic collection functionality.

Properties

Manager

Methods

LockCollection

RegisterDevice

UnlockCollection

UnregisterDevice


SerialChannel Object

The SerialChannel object provides means for serial communications. It derives from MPTChannel object and therefore implements basic channel functionality too.

Properties

Port

BaudRate

Parity

DataBits

StopBits

CRC

DevicePath

Handshake

XonChar

XoffChar

Methods

SetDTR

SetRTS

SetBreak

EnsureConnected


IrDAChannel Object

The IrDAChannel object provides means for IrDA communications. It derives from MPTChannel object and therefore implements basic channel functionality too.

Properties

Service

DeviceName

InstanceName

Methods

EnsureConnected


PacketOperation Object

The PacketOperation object records a set of channel operations. They are interpreted as a single complex operation and can be executed multiple times with a single method invocation.

Methods

AddOperation

Execute

ExecuteAsync

Reset


BaudRate Property

Applies to: SerialChannel object.

Gets or sets the baud rate for the serial channel.

Syntax

Visual Basic:

Property BaudRate as SerialBaudRates

Read / Write

Borland C++:

HRESULT get_BaudRate(/*[out,retval]*/ SerialBaudRates* pVal);

HRESULT set_BaudRate(/*[in]*/ SerialBaudRates newVal);

Microsoft Visual C++:

HRESULT get_BaudRate(/*[retval][out]*/ SerialBaudRates* pVal);

HRESULT put_BaudRate(/*[in]*/ SerialBaudRates newVal);

Parameters

pVal

Address of SerialBaudRates variable that receives channel's baud rate.

newVal

A value from SerialBaudRates enumeration specifying a new baud rate for the serial channel.

Return value

Visual Basic:

A SerialBaudRates representing channel's baud rate.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the baud rate does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialBaudRates


BufferSize Property

Applies to: MPTChannel object.

Gets or sets the size of the receiver's internal buffer. This is the number of bytes the buffer can take without overflow.

Syntax

Visual Basic:

Property BufferSize as Long

Read / Write

Borland C++:

HRESULT get_BufferSize(/*[out, retval]*/ long* pVal);

HRESULT set_BufferSize(/*[in]*/ long newVal);

Microsoft Visual C++:

HRESULT get_BufferSize(/*[retval][out]*/ long* pVal);

HRESULT put_BufferSize(/*[in]*/ long newVal);

Parameters

pVal

Address of long variable that receives the size of the buffer.

newVal

A long specifying the new size of the buffer.

Return value

Visual Basic:

A Long representing the size of the buffer.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReadBuffer, BytesInBuffer


Busy Property

Applies to: MPTChannel object.

Getsthe busy state of the channel. Clients must set the busy flag when they intend to start a prolonged operation (e.g. longer than 5 sec) and clear it at the end of the operation. This prevents other eventual clients from hanging for a long time when they try to lock the same channel.

Syntax

Visual Basic:

Property Busy as Boolean

Read / Write

Borland C++:

HRESULT get_Busy(/*[out, retval]*/ TOLEBOOL* pVal);

HRESULT set_Busy(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_Busy(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_Busy(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the channel - True - busy, False - not busy.

newVal

A Boolean specifying new state for the channel - True - busy, False - not busy.

Return value

Visual Basic:

A Boolean representing current state of the channel - True - busy, False - not busy.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

LockChannel, UnlockChannel


BytesInBuffer Property

Applies to: MPTChannel object.

Gets current capacity of the receiver's internal buffer. This can be a number between zero and the value of BufferSize property.

Syntax

Visual Basic:

Property BytesInBuffer as Long

Read only

Borland C++:

HRESULT get_BytesInBuffer(/*[out, retval]*/ long* pVal);

Microsoft Visual C++:

HRESULT get_BytesInBuffer(/*[retval][out]*/ long* pVal);

Parameters

pVal

Address of long variable that receives the capacity of the buffer.

Return value

Visual Basic:

A Long representing current capacity of the buffer.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid number.

Any other error code	The operation failed. *pVal contains zero.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReadBuffer


Channels Property

Applies to: CommManager object.

Gets the collection of currently activated MPTChannel objects. It is implemented by the MPTChannels object.

Syntax

Visual Basic:

Property Channels as Object

Read only

Borland C++:

HRESULT get_Channels(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Channels(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IMPTChannels (implemented by MPTChannels object) interfaces.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to the MPTChannels collection object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Devices


Connected Property

Applies to: MPTChannel object.

Gets or sets whether the channel is connected to its physical port. Channel operations, like Send, Receive, etc, are not permitted if the channel is not connected.

Syntax

Visual Basic:

Property Connected as Boolean

Read / Write

Borland C++:

HRESULT get_Connected(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_Connected(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_Connected(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_Connected(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the connection (True - connected, False - not).

newVal

A Boolean specifying the new state of the connection - True forces the channel to make an attempt to connect, False - to disconnect. In both cases, nothing happens if newVal is equal to current state.

Return value

Visual Basic:

A Boolean representing current state of the connection (True - connected, False - not).

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each channel can provide its own optimized method for connecting to the physical port.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


CRC Property

Applies to: SerialChannel object.

Gets or sets the type of the CRC calculation algorithm for the channel.

Syntax

Visual Basic:

Property CRC as MPTCRC

Read / Write

Borland C++:

HRESULT get_CRC(/*[out,retval]*/ MPTCRC* pVal);

HRESULT set_CRC(/*[in]*/ MPTCRC newVal);

Microsoft Visual C++:

HRESULT get_CRC(/*[retval][out]*/ MPTCRC* pVal);

HRESULT put_CRC(/*[in]*/ MPTCRC newVal);

Parameters

pVal

Address of MPTCRC variable that receives current CRC algorithm type.

newVal

A value from MPTCRC enumeration specifying the new CRC algorithm type.

Return value

Visual Basic:

A MPTCRC representing channel's CRC algorithm type.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

MPTCRC


DataBits Property

Applies to: SerialChannel object.

Gets or sets the data bits for the serial channel.

Syntax

Visual Basic:

Property DataBits as SerialDataBits

Read / Write

Borland C++:

HRESULT get_DataBits(/*[out,retval]*/ SerialDataBits* pVal);

HRESULT set_DataBits(/*[in]*/ SerialDataBits newVal);

Microsoft Visual C++:

HRESULT get_DataBits(/*[retval][out]*/ SerialDataBits* pVal);

HRESULT put_DataBits(/*[in]*/ SerialDataBits newVal);

Parameters

pVal

Address of SerialDataBits variable that receives channel's data bits.

newVal

A value from SerialDataBits enumeration specifying new data bits for the serial channel.

Return value

Visual Basic:

A SerialDataBits representing channel's data bits.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the data bits does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialDataBits


DeviceName Property

Applies to: IrDAChannel object.

Gets or sets the name of the infrared device to work with. Partial names are also accepted.

Syntax

Visual Basic:

Property DeviceName as String

Read / Write

Borland C++:

HRESULT get_DeviceName(/*[out,retval]*/ BSTR* pVal);

HRESULT set_DeviceName(/*[in]*/ BSTR newVal);

Microsoft Visual C++:

HRESULT get_DeviceName(/*[retval][out]*/ BSTR* pVal);

HRESULT put_DeviceName(/*[in]*/ BSTR newVal);

Parameters

pVal

Address of BSTR variable that receives the channel's infrared device name.

newVal

A BSTR specifying a new infrared device to work with.

Return value

Visual Basic:

A String representing the name of the infrared device that the channel is working with.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the device name does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. Although possible, it is not recommended to change the device name of an existing channel. Instead call CreateChannel method to create another object and Release your current channel. This ensures compatibility with MPT framework and any other activated channel clients.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Service, InstanceName


DevicePath Property

Applies to: SerialChannel object.

Gets or sets the device path for the serial channel. It can be "COMx" or a special string, provided by Windows, which is machine dependent and is used by the operating system for internal reference to the serial port.

Syntax

Visual Basic:

Property DevicePath as String

Read / Write

Borland C++:

HRESULT get_DevicePath(/*[out,retval]*/ BSTR* pVal);

HRESULT set_DevicePath(/*[in]*/ BSTR newVal);

Microsoft Visual C++:

HRESULT get_DevicePath(/*[retval][out]*/ BSTR* pVal);

HRESULT put_DevicePath(/*[in]*/ BSTR newVal);

Parameters

pVal

Address of BSTR variable that receives channel's device path.

newVal

A BSTR specifying a new device path for the serial channel.

Return value

Visual Basic:

A String representing channel's device path.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the device path does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. Although possible, it is not recommended to change the device path of an existing channel. Instead call CreateChannel method to create another object and Release your current channel. This ensures compatibility with MPT framework and any other activated channel clients.

Current serial channel implementation does not guarantee that this property will always hold a valid path. This can happen if the channel has been created using the Port number.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Devices Property

Applies to: CommManager object, MPTChannel object.

Gets the collection of currently registered MPTDevice objects. It is an MPTDevices object for the CommManager object and an ObjectCollection object for the MPTChannel object.

Syntax

Visual Basic:

Property Devices as Object

Read only

Borland C++:

HRESULT get_Devices(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Devices(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) and IMPTDevices (implemented by MPTDevices object) or respectively IObjectCollection (implemented by ObjectCollection object) interfaces.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to collection of device objects.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Channels, DispatchDeviceMessage


DispatchMessages Property

Applies to: MPTChannel object.

Gets or sets whether the channel will dispatch all window messages while blocked.

Syntax

Visual Basic:

Property DispatchMessages as Boolean

Read / Write

Borland C++:

HRESULT get_DispatchMessages(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_DispatchMessages(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_DispatchMessages(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_DispatchMessages(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the property.

newVal

A Boolean specifying the new state of the property.

Return value

Visual Basic:

A Boolean representing current state of the property.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Handshake Property

Applies to: SerialChannel object.

Gets or sets the type of serial flow control.

Syntax

Visual Basic:

Property Handshake as SerialFlowControl

Read / Write

Borland C++:

HRESULT get_Handshake(/*[out,retval]*/ SerialFlowControl* pVal);

HRESULT set_Handshake(/*[in]*/ SerialFlowControl newVal);

Microsoft Visual C++:

HRESULT get_Handshake(/*[retval][out]*/ SerialFlowControl* pVal);

HRESULT put_Handshake(/*[in]*/ SerialFlowControl newVal);

Parameters

pVal

Address of SerialFlowControl variable that receives current flow control.

newVal

A value from SerialFlowControl enumeration specifying new flow control for the serial channel.

Return value

Visual Basic:

A SerialFlowControl representing channel's handshaking.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the handshaking does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialFlowControl, XonChar, XoffChar


HashValue Property

Applies to: MPTChannel object.

Gets or sets an unique number associated with the channel.

Syntax

Visual Basic:

Property HashValue as Long

Read / Write

Borland C++:

HRESULT get_HashValue(/*[out,retval]*/ long* pVal);

HRESULT set_HashValue(/*[in]*/ long newVal);

Microsoft Visual C++:

HRESULT get_HashValue(/*[retval][out]*/ long* pVal);

HRESULT put_HashValue(/*[in]*/ long newVal);

Parameters

pVal

Address of long variable that receives current hash value.

newVal

A long specifying a new hash value for the channel.

Return value

Visual Basic:

A long representing current hash value.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each channel has an associated unique hash value, which is a 32-bit number, identifying the channel throughout the system.

Changing the hash value is provided only for custom channel implementations. Standard channels do not allow changing their hash values.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


InstanceName Property

Applies to: IrDAChannel object.

Gets the instance name of the infrared device that the channel is working with.

Syntax

Visual Basic:

Property InstanceName as String

Read only

Borland C++:

HRESULT get_InstanceName(/*[out,retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT get_InstanceName(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of BSTR variable that receives the channel's infrared device instance name.

Return value

Visual Basic:

A String representing the instance name of the infrared device that the channel is working with.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The instance name of the infrared device is unique throughout the system.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

DeviceName


LastError Property

Applies to: MPTChannel object.

Gets or sets information about the last error for the channel.

Syntax

Visual Basic:

Property LastError as ErrorCode

Read / Write

Borland C++:

HRESULT get_LastError(/*[out,retval]*/ ErrorCode* pVal);

HRESULT set_LastError(/*[in]*/ ErrorCode newVal);

Microsoft Visual C++:

HRESULT get_LastError(/*[retval][out]*/ ErrorCode* pVal);

HRESULT put_LastError(/*[in]*/ ErrorCode newVal);

Parameters

pVal

Address of ErrorCode variable that receives channel's last error.

newVal

A value from ErrorCode enumeration specifying a new error code for the channel. Only ecNoError will be accepted, because the last error can only be cleared, not changed.

Return value

Visual Basic:

A ErrorCode representing channel's last error.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ErrorCode


LocalEcho Property

Applies to: MPTChannel object.

Gets or sets whether local echo should be provided. If the local echo is turned on, all sent data is copied to the receiver's buffer right after it has been successfully transmitted.

Syntax

Visual Basic:

Property LocalEcho as Boolean

Read / Write

Borland C++:

HRESULT get_LocalEcho(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_LocalEcho(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_LocalEcho(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_LocalEcho(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives True if the local echo is turned on, False otherwise.

newVal

A Boolean turning on (if it is True) or off (if it is False) the local echo. The channel must be locked from the calling client or the operation will fail.

Return value

Visual Basic:

A Boolean that is True if the local echo is turned on, False otherwise.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Locked Property

Applies to: MPTChannel object.

Indicates whether the channel is locked from another client.

Syntax

Visual Basic:

Property Locked as Boolean

Read only

Borland C++:

HRESULT get_Locked(/*[out, retval]*/ TOLEBOOL* pVal);

Microsoft Visual C++:

HRESULT get_Locked(/*[retval][out]*/ VARIANT_BOOL* pVal);

Parameters

pVal

Address of Boolean variable that receives the lock status - True - locked (not accessible), False - free (accessible).

Return value

Visual Basic:

A Boolean representing the lock status of the channel - True - locked (not accessible), False - free (accessible).

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal does not contain a valid value.

Remarks

When locked from a particular client, a channel executes only operations requested from that client. All other requests are queued for a subsequent execution after the channel is unlocked.

Locked returns False if the channel is available, which means it has been locked from current client or is not locked at all. Otherwise Locked is True.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

LockChannel, UnlockChannel


Logging Property

Applies to: MPTChannel object.

Gets or sets whether the channel will log all the data transfered through it.

Syntax

Visual Basic:

Property Logging as Boolean

Read / Write

Borland C++:

HRESULT get_Logging(/*[out,retval]*/ TOLEBOOL* pVal);

HRESULT set_Logging(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT get_Logging(/*[retval][out]*/ VARIANT_BOOL* pVal);

HRESULT put_Logging(/*[in]*/ VARIANT_BOOL newVal);

Parameters

pVal

Address of Boolean variable that receives current state of the property.

newVal

A Boolean specifying the new state of the property.

Return value

Visual Basic:

A Boolean representing current state of the property.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Manager Property

Applies to: MPTChannels object, MPTDevices object, MPTChannel object.

Gets a reference to current instance of the CommManager object.

Syntax

Visual Basic:

Property Manager as Object

Read only

Borland C++:

HRESULT get_Manager(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Manager(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the manager object. If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to the CommManager object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Name Property

Applies to: CommManager object, MPTChannel object.

Gets or sets the name of the corresponding object.

Syntax

Visual Basic:

Property Name as String

Read only for CommManager object, read / write for MPTChannel object

Borland C++:

HRESULT get_Name(/*[out, retval]*/ BSTR* pVal);

HRESULT set_Name(/*[in]*/ BSTR newVal);	// Only for MPTChannel object

Microsoft Visual C++:

HRESULT get_Name(/*[retval][out]*/ BSTR* pVal);

HRESULT put_Name(/*[in]*/ BSTR newVal);	// Only for MPTChannel object

Parameters

pVal

Address of BSTR variable that receives the name of the object. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

newVal

A new name to be used for the channel.

Return value

Visual Basic:

A String representing the name of the object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Remarks

Depending on the channel type, the Name property can be used to identify the communication port while attempting to connect. Normally, once created and associated with a port, a channel remains in this state until destroyed. Therefore, in most cases, the value of this property should not be changed. It is provided mainly for reading.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Parent Property

Applies to: MPTChannel object.

Gets the parent of an object. This is the MPTChannels collection object.

Syntax

Visual Basic:

Property Parent as Object

Read only

Borland C++:

HRESULT get_Parent(/*[out, retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT get_Parent(/*[retval][out]*/ IDispatch** ppVal);

Parameters

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the parent object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to an object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Parity Property

Applies to: SerialChannel object.

Gets or sets the parity for the serial channel.

Syntax

Visual Basic:

Property Parity as SerialParity

Read / Write

Borland C++:

HRESULT get_Parity(/*[out,retval]*/ SerialParity* pVal);

HRESULT set_Parity(/*[in]*/ SerialParity newVal);

Microsoft Visual C++:

HRESULT get_Parity(/*[retval][out]*/ SerialParity* pVal);

HRESULT put_Parity(/*[in]*/ SerialParity newVal);

Parameters

pVal

Address of SerialParity variable that receives channel's parity.

newVal

A value from SerialParity enumeration specifying a new parity for the serial channel.

Return value

Visual Basic:

A SerialParity representing channel's parity.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the parity does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialParity


Port Property

Applies to: SerialChannel object.

Gets or sets the number of the underlying serial port.

Syntax

Visual Basic:

Property Port as SerialPortNumber

Read / Write

Borland C++:

HRESULT get_Port(/*[out,retval]*/ SerialPortNumber* pVal);

HRESULT set_Port(/*[in]*/ SerialPortNumber newVal);

Microsoft Visual C++:

HRESULT get_Port(/*[retval][out]*/ SerialPortNumber* pVal);

HRESULT put_Port(/*[in]*/ SerialPortNumber newVal);

Parameters

pVal

Address of SerialPortNumber variable that receives channel's port number.

newVal

A value from SerialPortNumber enumeration specifying a new port to be used.

Return value

Visual Basic:

A SerialPortNumber representing channel's port number.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the port number does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. Although possible, it is not recommended to change the port number of an existing channel. Instead call CreateChannel method to create another object and Release your current channel. This ensures compatibility with MPT framework and any other activated channel clients.

Current serial channel implementation does not guarantee that this property will always hold a valid port number. This can happen if the channel has been created using the DevicePath string, which is the preferred way to create a serial channel.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialPortNumber


Remote Property

Applies to: MPTChannel object.

Indicates whether the channel is created and hosted in a different process.

Syntax

Visual Basic:

Property Remote as Boolean

Read only

Borland C++:

HRESULT get_Remote(/*[out, retval]*/ TOLEBOOL* pVal);

Microsoft Visual C++:

HRESULT get_Remote(/*[retval][out]*/ VARIANT_BOOL* pVal);

Parameters

pVal

Address of Boolean variable that receives the remote status - True - remote channel, False - local channel.

Return value

Visual Basic:

A Boolean representing the remote status of the channel - True - remote, False - local.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal contains False.

Remarks

Channel operations execute faster on local channels.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


SendDelay Property

Applies to: MPTChannel object.

Gets or sets the delay time in ms between sent bytes. The channel inserts this time gap before sending each byte.

Syntax

Visual Basic:

Property SendDelay as Long

Read / Write

Borland C++:

HRESULT get_SendDelay(/*[out,retval]*/ long* pVal);

HRESULT set_SendDelay(/*[in]*/ long newVal);

Microsoft Visual C++:

HRESULT get_SendDelay(/*[retval][out]*/ long* pVal);

HRESULT put_SendDelay(/*[in]*/ long newVal);

Parameters

pVal

Address of long variable that receives current send delay time.

newVal

A long specifying a new send delay time for the channel.

Return value

Visual Basic:

A long representing current send delay time.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The default SendDelay is zero, which means that data is sent as fast as possible.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Service Property

Applies to: IrDAChannel object.

Gets or sets the service of the underlying Windows socket. Currently, only IRCOMM 9-wire service is supported.

Syntax

Visual Basic:

Property Service as MPTIrDAService

Read / Write

Borland C++:

HRESULT get_Service(/*[out,retval]*/ MPTIrDAService* pVal);

HRESULT set_Service(/*[in]*/ MPTIrDAService newVal);

Microsoft Visual C++:

HRESULT get_Service(/*[retval][out]*/ MPTIrDAService* pVal);

HRESULT put_Service(/*[in]*/ MPTIrDAService newVal);

Parameters

pVal

Address of MPTIrDAService variable that receives the channel's socket service.

newVal

A value from MPTIrDAService enumeration specifying a new service to be used.

Return value

Visual Basic:

A MPTIrDAService representing the channel's socket service.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the socket service does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the IrDA channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

DeviceName


Status Property

Applies to: MPTChannel object.

Gets the channel status.

Syntax

Visual Basic:

Property Status as ChannelStatus

Read only

Borland C++:

HRESULT get_Status(/*[out, retval]*/ ChannelStatus* pVal);

Microsoft Visual C++:

HRESULT get_Status(/*[retval][out]*/ ChannelStatus* pVal);

Parameters

pVal

Address of ChannelStatus variable that receives current status of the channel.

Return value

Visual Basic:

A ChannelStatus representing current status of the channel.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal does not contain a valid value.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ChannelStatus


StopBits Property

Applies to: SerialChannel object.

Gets or sets the stop bits for the serial channel.

Syntax

Visual Basic:

Property StopBits as SerialStopBits

Read / Write

Borland C++:

HRESULT get_StopBits(/*[out,retval]*/ SerialStopBits* pVal);

HRESULT set_StopBits(/*[in]*/ SerialStopBits newVal);

Microsoft Visual C++:

HRESULT get_StopBits(/*[retval][out]*/ SerialStopBits* pVal);

HRESULT put_StopBits(/*[in]*/ SerialStopBits newVal);

Parameters

pVal

Address of SerialStopBits variable that receives channel's stop bits.

newVal

A value from SerialStopBits enumeration specifying new stop bits for the serial channel.

Return value

Visual Basic:

A SerialStopBits representing channel's stop bits.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the stop bits does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SerialStopBits


Timeout Property

Applies to: MPTChannel object.

Gets or sets the timeout in ms for the channel operations. This is the maximum time to wait for an operation to be executed. This avoids deadlocks and thread hangs if the completion response from the channel for the particular operation has been lost for some reason.

Syntax

Visual Basic:

Property Timeout as Long

Read / Write

Borland C++:

HRESULT get_Timeout(/*[out,retval]*/ long* pVal);

HRESULT set_Timeout(/*[in]*/ long newVal);

Microsoft Visual C++:

HRESULT get_Timeout(/*[retval][out]*/ long* pVal);

HRESULT put_Timeout(/*[in]*/ long newVal);

Parameters

pVal

Address of long variable that receives current timeout.

newVal

A long specifying a new timeout for the channel.

Return value

Visual Basic:

A long representing current timeout.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The default timeout is 30sec (30000).

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Type Property

Applies to: MPTChannel object.

Gets the type of the channel.

Syntax

Visual Basic:

Property Type as ChannelType

Read only

Borland C++:

HRESULT get_Type(/*[out, retval]*/ ChannelType* pVal);

Microsoft Visual C++:

HRESULT get_Type(/*[retval][out]*/ ChannelType* pVal);

Parameters

pVal

Address of ChannelType variable that receives the type of the channel.

Return value

Visual Basic:

A ChannelType representing the type of the channel.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal does not contain a valid value.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ChannelType


XoffChar Property

Applies to: SerialChannel object.

Gets or sets the Xoff character for the serial port. It is used if the Handshake property contains fcSoftware, otherwise is ignored.

Syntax

Visual Basic:

Property XoffChar as Byte

Read / Write

Borland C++:

HRESULT get_XoffChar(/*[out,retval]*/ unsigned_char* pVal);

HRESULT set_XoffChar(/*[in]*/ unsigned_char newVal);

Microsoft Visual C++:

HRESULT get_XoffChar(/*[retval][out]*/ unsigned char* pVal);

HRESULT put_XoffChar(/*[in]*/ unsigned char newVal);

Parameters

pVal

Address of Byte variable that receives current Xoff character.

newVal

A Byte value specifying a new Xoff character to be used.

Return value

Visual Basic:

A Byte with the Xoff character.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the Xoff character does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

XonChar


XonChar Property

Applies to: SerialChannel object.

Gets or sets the Xon character for the serial port. It is used if the Handshake property contains fcSoftware, otherwise is ignored.

Syntax

Visual Basic:

Property XonChar as Byte

Read / Write

Borland C++:

HRESULT get_XonChar(/*[out,retval]*/ unsigned_char* pVal);

HRESULT set_XonChar(/*[in]*/ unsigned_char newVal);

Microsoft Visual C++:

HRESULT get_XonChar(/*[retval][out]*/ unsigned char* pVal);

HRESULT put_XonChar(/*[in]*/ unsigned char newVal);

Parameters

pVal

Address of Byte variable that receives current Xon character.

newVal

A Byte value specifying a new Xon character to be used.

Return value

Visual Basic:

A Byte with the Xon character.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Changing the Xon character does not affect current connection session. You should manually disconnect and connect the channel for the changes to take effect. In addition, the serial channel provides a special, optimized EnsureConnected method, which can do this in a single step.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

XoffChar


Activate Method

Applies to: MPTChannel object.

Performs final initialization routines and puts the channel into 'ready for work' state.

Syntax

Visual Basic:

Sub Activate(Param)

Borland C++:

HRESULT Activate(/*[in]*/ TVariantInParam Param);

Microsoft Visual C++:

HRESULT Activate(/*[in]*/ VARIANT Param);

Parameters

Param

A VARIANT containing an activation parameter. It can be a simple Boolean, or an array of VARIANTs, one parameter for each object in the chain of activation.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


AddOperation Method

Applies to: PacketOperation object.

Records the specified operation.

Syntax

Visual Basic:

Function AddOperation(Type as OperationCodes, Param, ResponseTimeout as Long) as Long

Borland C++:

HRESULT AddOperation(/*[in]*/ OperationCodes Type,

                                        /*[in]*/ TVariantInParam Param,

                                        /*[in]*/ long ResponseTimeout,

                                        /*[out,retval]*/ long* Cookie);

Microsoft Visual C++:

HRESULT AddOperation(/*[in]*/ OperationCodes type,

                                        /*[in]*/ VARIANT Param,

                                        /*[in]*/ long ResponseTimeout,

                                        /*[retval][out]*/ long* Cookie);

Parameters

Type

A value from the OperationCodes enumeration specifying the type of the operation.

Param

A VARIANT containing a parameter for the operation. Its value depends on the type of the operation:

Type	Containment of Param

ocSend	Can be a Byte, Integer, Long, an array of them or a String. This is the data to be sent.

ocReceive	A numeric value, specifying the number of bytes to receive.

ocMLXReceive	Ignored. Can be anything.

ocMLXCommand	Can be a Byte, Integer, Long, an array of them or a String. This is the data to be sent.

ocDelay	A numeric value, specifying the delay time in ms.

ocFlush	A value from the FlushFlags enumeration, specifying the buffers to be cleared.

ResponseTimeout

A long specifying how much time, in ms, to wait for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is used if Type is ocReceive, ocMLXReceive or ocMLXCommand. Otherwise it is ignored and can be anything.

Cookie

Address of long variable that receives a cookie which identifies the operation. The following is a list of the usage of the cookie:

Type	Cookie is returned?	Response is received?

ocSend	No. Zero is returned.	No. Events are fired only if an error occurs during execution.

ocReceive	Yes. Cookie must not be NULL.	Yes - OnReceivePacket with the returned cookie.

ocMLXReceive	Yes. Cookie must not be NULL.	Yes - OnReceivePacket with the returned cookie.

ocMLXCommand	Yes. Cookie must not be NULL.	Yes - OnReceivePacket with the returned cookie.

ocDelay	No. Zero is returned.	No. Events are fired only if an error occurs during execution.

ocFlush	No. Zero is returned.	No. Events are fired only if an error occurs during execution.

The returned cookie is valid until the object is released or cleared and can be reused multiple times.

Return value

Visual Basic:

A Long representing a cookie which identifies the operation. Can be zero if the operation does not require a cookie.

This cookie is valid until the object is released or cleared and can be reused multiple times.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Reset, Execute, ExecuteAsync, OnReceivePacket


AttachDevice Method

Applies to: MPTChannel object.

Registers the specified device with the channel. This registration keeps a reference to the object until is it unregistered with DetachDevice method.

Syntax

Visual Basic:

Sub AttachDevice(pVal as Object)

Borland C++:

HRESULT AttachDevice(/*[in]*/ LPDISPATCH pVal);

Microsoft Visual C++:

HRESULT AttachDevice(/*[in]*/ IDispatch* pVal);

Parameters

pVal

A pointer to an instance of IDispatch implementation. It must implement at least IMPTDevice interface in order to be eligible for registration.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Usually MPTDevice objects automatically attach and detach themselves with the channels.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

DetachDevice


CancelOperation Method

Applies to: MPTChannel object.

Aborts the specified asynchronous operation or all operations scheduled by the calling thread.

Syntax

Visual Basic:

Sub CancelOperation([Cookie as Long = 0])

Borland C++:

HRESULT CancelOperation(/*[in,def,opt]*/ long Cookie);

Microsoft Visual C++:

HRESULT CancelOperation(/*[defaultvalue][in]*/ long Cookie = 0);

Parameters

Cookie

A long specifying a cookie for the operation to be aborted. If it is zero all operations, scheduled by the calling thread, will be canceled. Optional, default value is 0.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


ChannelsCanBeCreated Method

Applies to: MPTChannels object.

Checks if it is possible to create channels of the specified type(s). For example, IrDA channels can be created if the system has properly installed IrDA port(s) and the associated software.

Syntax

Visual Basic:

Function ChannelsCanBeCreated(ct as ChannelType) as Boolean

Borland C++:

HRESULT ChannelsCanBeCreated(/*[in]*/ ChannelType ct, /*[out,retval]*/ VARIANT_BOOL* pVal);

Microsoft Visual C++:

HRESULT ChannelsCanBeCreated(/*[in]*/ ChannelType ct, /*[retval][out]*/ VARIANT_BOOL* pVal);

Parameters

ct

A value from the ChannelType enumeration, which specifies the type of channels of interest. Can be a combination of channel types.

pVal

Address of Boolean variable that receives the return value of the function. It is VARIANT_TRUE if channels can be created, VARIANT_FALSE otherwise.

Return value

Visual Basic:

True if channels of the specified type can be created, False otherwise.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains valid value.

Any other error code	The operation failed. *pVal contains VARIANT_FALSE.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

CreateChannel


CreateChannel Method

Applies to: MPTChannels object.

Creates and initializes a new MPTChannel object.

Syntax

Visual Basic:

Function CreateChannel(Param, ct as ChannelType) as Object

Borland C++:

HRESULT CreateChannel(/*[in]*/ TVariantInParam Param, /*[in]*/ ChannelType ct, /*[out,retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT CreateChannel(/*[in]*/ VARIANT Param, /*[in]*/ ChannelType ct, /*[retval][out]*/ IDispatch** ppVal);

Parameters

Param

Initialization data for the channel. It's value is interpreted depending on the ct parameter:

Channel type	Value of Param

Serial	Can be a string, like "COM1" or an integer number, representing the serial port, taken from the SerialPortNumber enumeration.

Parallel	The meaning of this parameter is not yet defined.

USB	The meaning of this parameter is not yet defined.

IrDA	A string which identifies the name of the device to connect to.

ct

A value from the ChannelType enumeration which specifies the type of the channel to be created. This must be a single channel type, a combination of types is not allowed.

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the channel. It can be safely queried for IMPTChannel (implemented by MPTChannel object) and one of the interfaces that derive from IMPTChannel, depending on the type of the newly created channel object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to a MPTChannel object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Remarks

A channel is not created if it already exists. Instead a reference to the existing channel is returned. This allows the channels to be shared between clients even if they reside in different processes.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ChannelsCanBeCreated, FindChannel


CreatePacketOperation Method

Applies to: MPTChannel object.

Creates an instance of PacketOperation object. It is associated with that channel and cannot be used with another one.

Syntax

Visual Basic:

Function CreatePacketOperation() as Object

Borland C++:

HRESULT CreatePacketOperation(/*[out,retval]*/ LPDISPATCH* PackObj);

Microsoft Visual C++:

HRESULT CreatePacketOperation(/*[retval][out]*/ IDispatch** PackObj);

Parameters

PackObj

Address of IDispatch* pointer variable that receives the interface pointer to the object. It can be safely queried for IPacketOperation (implemented by PacketOperation object) interface.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to a PacketOperation object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *PackObj contains a valid pointer.

Any other error code	The operation failed. *PackObj contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


Delay Method

Applies to: MPTChannel object.

Blocks the channel for the specified time.

Syntax

Visual Basic:

Sub Delay(ms as Long)

Borland C++:

HRESULT Delay(/*[in]*/ long ms);

Microsoft Visual C++:

HRESULT Delay(/*[in]*/ long ms);

Parameters

ms

A long specifying a time interval, in ms, to suspend the channel operations.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

This method does not return upon the completion of the operation. The request passes through the associated queue in the channel.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

DelayAsync


DelayAsync Method

Applies to: MPTChannel object.

Asynchronously blocks the channel for the specified time.

Syntax

Visual Basic:

Function DelayAsync(ms as Long) as Long

Borland C++:

HRESULT DelayAsync(/*[in]*/ long ms, /*[out, retval]*/ long* Cookie);

Microsoft Visual C++:

HRESULT DelayAsync(/*[in]*/ long ms, /*[retval][out]*/ long* Cookie);

Parameters

ms

A long specifying a time interval, in ms, to suspend the channel operations.

Cookie

Address of long variable that receives a cookie which identifies the operation. This value must be used when sinking OnDelayComplete event.

You can pass NULL if completion notification is not needed and should not be fired. This improves the performance.

Return value

Visual Basic:

A Long representing a cookie which identifies the operation.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. If provided, *Cookie contains zero.

S_FALSE	The operation completed successfully but the request is still pending. If provided, *Cookie contains a valid cookie for the operation.

Any other error code	The operation failed. If provided, *Cookie contains zero.

Remarks

The request passes through the associated queue in the channel.

This method schedules the request and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case no cookie is returned even if Cookie parameter contains a valid pointer (actually zero is returned) and OnSendComplete event is not fired.

If the returned cookie is valid, it can be used to abort the operation with a call to CancelOperation method.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Delay


DetachDevice Method

Applies to: MPTChannel object.

Unregisters the specified device from the channel.

Syntax

Visual Basic:

Sub DetachDevice(pVal as Object)

Borland C++:

HRESULT DetachDevice(/*[in]*/ LPDISPATCH pVal);

Microsoft Visual C++:

HRESULT DetachDevice(/*[in]*/ IDispatch* pVal);

Parameters

pVal

A pointer to an instance of IDispatch implementation. It has to implement at least IMPTDevice interface in order to be eligible for unregistration.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The operation did not failed but the specified device is not attached to this channel.

Any other error code	The operation failed.

Remarks

Usually MPTDevice objects automatically attach and detach themselves with the channels.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

AttachDevice


DispatchDeviceMessage Method

Applies to: MPTChannel object.

Sends a message to the attached device objects.

Syntax

Visual Basic:

Sub DispatchDeviceMessage(pSender as Object, lMessage as Long, [args])

Borland C++:

HRESULT DispatchDeviceMessage(/*[in]*/ LPDISPATCH pSender,

                                                        /*[in]*/ long lMessage,

                                                        /*[in,opt]*/ TVariantInParam args);

Microsoft Visual C++:

HRESULT DispatchDeviceMessage(/*[in]*/ IDispatch* pSender,

                                                        /*[in]*/ long lMessage,

                                                        /*[optional][in]*/ VARIANT args);

Parameters

pSender

A pointer to an instance of IDispatch implementation. This is the object that initiates the operation and therefore it will not receive the message.

lMessage

A long specifying the message.

args

A VARIANT specifying additional message data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The function iterates over the registered device objects and simply calls their implementations of OnMessage method.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


EnsureConnected Method (IrDA channel)

Applies to: IrDAChannel object.

Compares provided settings with their counterparts in the IrDA channel. If not equal, the channel is disconnected and connected again. This method also works if the channel is not currently connected.

Syntax

Visual Basic:

Sub EnsureConnected(DeviceName as String, [srvc as MPTIrDAService = MPT_IrCOMM_9wire])

Borland C++:

HRESULT EnsureConnected(/*[in]*/ BSTR DeviceName, /*[in,def,opt]*/ MPTIrDAService srvc);

Microsoft Visual C++:

HRESULT EnsureConnected(/*[in]*/ BSTR DeviceName,

                                              /*[defaultvalue][in]*/ MPTIrDAService srvc = MPT_IrCOMM_9wire);

Parameters

DeviceName

A String specifying the name of the infrared device for the IrDA channel. Partial names are also accepted.

srvc

A value from MPTIrDAService enumeration specifying the channel's socket service. Optional, default value is MPT_IrCOMM_9wire.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

DeviceName, Service


EnsureConnected Method (serial channel)

Applies to: SerialChannel object.

Compares provided settings with their counterparts in the serial channel. If not equal, the channel is disconnected and connected again. This method also works if the channel is not currently connected.

Syntax

Visual Basic:

Sub EnsureConnected(baud as SerialBaudRates, [DataBits as SerialDataBits = DB8], [StopBits as SerialStopBits = OneStopBit], [Parity as SerialParity = NoParity], [CRC as MPTCRC = crcNone], [flow as SerialFlowControl = fcNone], [Xon as Byte = 0], [Xoff as Byte = 0])

Borland C++:

HRESULT EnsureConnected(/*[in]*/ SerialBaudRates baud,

                                              /*[in,def,opt]*/ SerialDataBits DataBits,

                                              /*[in,def,opt]*/ SerialStopBits StopBits,

                                              /*[in,def,opt]*/ SerialParity Parity,

                                              /*[in,def,opt]*/ MPTCRC CRC,

                                              /*[in,def,opt]*/ SerialFlowControl flow,

                                              /*[in,def,opt]*/ unsigned_char Xon,

                                              /*[in,def,opt]*/ unsigned_char Xoff);

Microsoft Visual C++:

HRESULT EnsureConnected(/*[in]*/ SerialBaudRates baud,

                                              /*[defaultvalue][in]*/ SerialDataBits DataBits = DB8,

                                              /*[defaultvalue][in]*/ SerialStopBits StopBits = OneStopBit,

                                              /*[defaultvalue][in]*/ SerialParity Parity = NoParity,

                                              /*[defaultvalue][in]*/ MPTCRC CRC = crcNone,

                                              /*[defaultvalue][in]*/ SerialFlowControl flow = fcNone,

                                              /*[defaultvalue][in]*/ unsigned char Xon = 0,

                                              /*[defaultvalue][in]*/ unsigned char Xoff = 0);

Parameters

baud

A value from SerialBaudRates enumeration specifying the required baud rate for the serial channel.

DataBits

A value from SerialDataBits enumeration specifying the required data bits for the serial channel. Optional, default value is DB8.

StopBits

A value from SerialStopBits enumeration specifying the required stop bits for the serial channel. Optional, default value is OneStopBit.

Parity

A value from SerialParity enumeration specifying the required parity bits for the serial channel. Optional, default value is NoParity.

CRC

A value from MPTCRC enumeration specifying the CRC algorithm for the serial channel. Optional, default value is crcNone.

flow

A value from SerialFlowControl enumeration specifying the type of handshaking. Optional, default value is fcNone.

Xon

A Byte value specifying the Xon character. It is used if flow is fcSoftware, otherwise is ignored. Optional, default value is 0.

Xoff

A Byte value specifying the Xoff character. It is used if flow is fcSoftware, otherwise is ignored. Optional, default value is 0.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

BaudRate, DataBits, StopBits, Parity, CRC, Handshake


EnumChannels Method

Applies to: MPTChannels object.

Returns a collection with all accessible channels of the specified type.

Syntax

Visual Basic:

Function EnumChannels(ct as ChannelType) as Object

Borland C++:

HRESULT EnumChannels(/*[in]*/ ChannelType ct, /*[out,retval]*/ LPDISPATCH* ppVal);

Microsoft Visual C++:

HRESULT EnumChannels(/*[in]*/ ChannelType ct, /*[retval][out]*/ IDispatch** ppVal);

Parameters

ct

A value from the ChannelType enumeration, which specifies the type of channels of interest. If ctAll is used, all possible channels of all types will be returned.

ppVal

Address of IDispatch* pointer variable that receives the interface pointer to the collection object. It can be safely queried for IMPTCollection (implemented by MPTCollection object) interface.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to a MPTChannelsSimple object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppVal contains a valid pointer.

Any other error code	The operation failed. *ppVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

EnumChannelStr


EnumChannelsStr Method

Applies to: MPTChannels object.

Creates an array with the names of all accessible channels of the specified type on current machine.

Syntax

Visual Basic:

Function EnumChannelsStr(ct as ChannelType)

Borland C++:

HRESULT EnumChannelsStr(/*[in]*/ ChannelType ct, /*[out,retval]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT EnumChannelsStr(/*[in]*/ ChannelType ct, /*[retval][out]*/ VARIANT* pVal);

Parameters

ct

A value from the ChannelType enumeration, which specifies the type of channels of interest. If ctAll is used, then the names of all possible channels of all types will be returned.

pVal

Address of VARIANT variable that receives an array of strings with the names of the channels.

If the invocation succeeds, the caller is responsible for calling VariantClear on the variable when it is no longer needed.

Return value

Visual Basic:

An array of Strings with the names of the channels.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

Any other error code	The operation failed. *pVal contains Empty (VT_EMPTY).

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

EnumChannels


Execute Method

Applies to: PacketOperation object.

Synchronously schedules this packet operation for an execution with its associated channel.

Syntax

Visual Basic:

Sub Execute()

Borland C++:

HRESULT Execute();

Microsoft Visual C++:

HRESULT Execute();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

This method does not return upon the completion of the whole packet operation.

Once recorded, a packet operation can be executed unlimited number of times.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

AddOperation, Reset, ExecuteAsync


ExecuteAsync Method

Applies to: PacketOperation object.

Asynchronously schedules this packet operation for an execution with its associated channel.

Syntax

Visual Basic:

Function ExecuteAsync() as Long

Borland C++:

HRESULT ExecuteAsync(/*[out,retval]*/ long* Cookie);

Microsoft Visual C++:

HRESULT ExecuteAsync(/*[retval][out]*/ long* Cookie);

Parameters

Cookie

Address of long variable that receives a cookie which identifies the packet operation. This value must be used when sinking OnPacketOperationComplete event.

You can pass NULL if completion notification is not needed and should not be fired. This improves the performance.

Return value

Visual Basic:

A Long representing a cookie which identifies the packet operation.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. If provided, *Cookie contains zero.

S_FALSE	The operation completed successfully but the request is still pending. If provided, *Cookie contains a valid cookie for the packet operation.

Any other error code	The operation failed. If provided, *Cookie contains zero.

Remarks

Once recorded, a packet operation can be executed unlimited number of times.

This method schedules a packet request and returns immediately. However, it is possible the whole packet operation to complete before the returning of the method. In this case no cookie is returned even if Cookie parameter contains a valid pointer (actually zero is returned) and OnPacketOperationComplete event is not fired.

If the returned cookie is valid, it can be used to abort the whole packet operation with a single call to CancelOperation method. This also aborts all recorded operations.

OnReceivePacket events are always fired during the execution of the packet operation.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

AddOperation, Reset, Execute


FindChannel Method

Applies to: MPTChannels object.

Given a channel's hash value, returns a channel object. The object must exist, this function does not create new channels.

Syntax

Visual Basic:

Function FindChannel(Hash as Long) as Object

Borland C++:

HRESULT FindChannel(/*[in]*/ long Hash, /*[out,retval]*/ LPDISPATCH* pVal);

Microsoft Visual C++:

HRESULT FindChannel(/*[in]*/ long Hash, /*[retval][out]*/ IDispatch** pVal);

Parameters

Hash

A long which specifies the channel's hash value.

pVal

Address of IDispatch* pointer variable that receives the interface pointer to the channel object.

If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed.

Return value

Visual Basic:

A reference to a MPTChannel object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid pointer.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

CreateChannel


Flush Method

Applies to: MPTChannel object.

Clears the internal buffers of the channel. This operation is synchronized through the associated request queue, however the method does not wait for its completion and returns immediately.

Syntax

Visual Basic:

Sub Flush([flags as FlushFlags = ffBoth])

Borland C++:

HRESULT Flush(/*[in,def,opt]*/ FlushFlags flags);

Microsoft Visual C++:

HRESULT Flush(/*[defaultvalue][in]*/ FlushFlags flags = ffBoth);

Parameters

flags

A value from the FlushFlags enumeration specifying which buffer to clear. Optional, default value is ffBoth.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


GetVersion Method

Applies to: CommManager object.

Gets the version of the software implementation of the communication layer.

Syntax

Visual Basic:

Sub GetVersion(pMajor As Long, pMinor As Long)

Borland C++:

HRESULT GetVersion(/*[out]*/ long *pMajor, /*[out]*/ long *pMinor);

Microsoft Visual C++:

HRESULT GetVersion(/*[ref][out]*/ long *pMajor, /*[ref][out]*/ long *pMinor);

Parameters

pMajor

Address of a Long variable that receives the major part of the version.

pMinor

Address of a Long variable that receives the minor part of the version.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pMajor and *pMinor contain valid numbers.

Any other error code	The operation failed. *pMajor and *pMinor contain 0.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

GetVersionStr


GetVersionStr Method

Applies to: CommManager object.

Gets the version of the software implementation of the communication layer as a string.

Syntax

Visual Basic:

Function GetVersionStr() As String

Borland C++:

HRESULT GetVersionStr(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT GetVersionStr(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of a BSTR variable that receives the string with the version. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the version of the module.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

GetVersion


Load Method

Applies to: MPTChannel object.

Initializes the channel object from a storage. In fact this method does nothing for standard channels, because they are automatically initialized from the storage routines.

Syntax

Visual Basic:

Sub Load(pStorage as Object)

Borland C++:

HRESULT Load(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Load(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Save


LockChannel Method

Applies to: MPTChannel object.

Attempts to gain an exclusive access to the channel. A locked channel serves only requests scheduled from its owner thread. All other requests remain in their queues until the channel is unlocked.

Syntax

Visual Basic:

Sub LockChannel([checkBusy as Boolean = True])

Borland C++:

HRESULT LockChannel(/*[in,def,opt]*/ TOLEBOOL checkBusy);

Microsoft Visual C++:

HRESULT LockChannel(/*[defaultvalue][in]*/ VARIANT_BOOL checkBusy = VARIANT_TRUE);

Parameters

checkBusy

A Boolean specifying whether the channel should first check its busy flag. If both checkBusy and the busy flag are True, LockChannel returns an error and does not try to lock the channel at all. Optional, default value is True.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The calling thread is blocked until the channel confirms that it is owned by the thread.

Each successful call to LockChannel must be balanced by a subsequent call to UnlockChannel. The channel is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a channel it already owns.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

UnlockChannel, Busy


LockCollection Method

Applies to: MPTDevices object.

Attempts to gain an exclusive access to the collection. A locked collection serves only requests scheduled from its owner thread. All other requests remain in their queues until the collection is unlocked.

Syntax

Visual Basic:

Sub LockCollection()

Borland C++:

HRESULT LockCollection();

Microsoft Visual C++:

HRESULT LockCollection();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The calling thread is blocked until the collection confirms that it is owned by the thread.

Each successful call to LockCollection must be balanced by a subsequent call to UnlockCollection. The collection is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a collection it already owns.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in CommUnit.dll

See also

UnlockCollection


MLXCommand Method

Applies to: MPTChannel object.

Synchronously executes a command sequence. This method should be used to communicate with Melexis devices that support MPT communication protocol. The command expects a response from the device.

Logically this method is equivalent to the following sequence (using Visual Basic notation):

Flush(ffBoth)

SendAsync(Data)

Data = MLXReceive(ResponseTimeout)

however it is optimized and therefore executes faster.

Syntax

Visual Basic:

Sub MLXCommand(ByRef Data, ResponseTimeout as Long)

Borland C++:

HRESULT MLXCommand(/*[in,out]*/ TVariant* Data, /*[in]*/ long ResponseTimeout);

Microsoft Visual C++:

HRESULT MLXCommand(/*[ref][out][in]*/ VARIANT* Data, /*[in]*/ long ResponseTimeout);

Parameters

Data

Address of VARIANT variable that holds the data to be sent and also receives the returned data. If the method succeeds it is an array of bytes (VT_ARRAY | VT_UI1), otherwise it is Empty (VT_EMPTY).

On return, *Data does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

ResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *Data contains valid data.

Any other error code	The operation failed. *Data is Empty (VT_EMPTY).

Remarks

This method does not return upon the completion of the operation. Before returning it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

MLXCommandAsync, ChannelMLXCommand, ChannelMLXCommandAsync


MLXCommandAsync Method

Applies to: MPTChannel object.

Asynchronously executes a command sequence. This method should be used to communicate with Melexis devices that support MPT communication protocol. The command expects a response from the device.

Logically this method is equivalent to the following sequence (using Visual Basic notation):

Flush(ffBoth)

SendAsync(Data)

Data = MLXReceiveAsync(ResponseTimeout)

however it is optimized and therefore executes faster.

Syntax

Visual Basic:

Sub MLXCommandAsync(ByRef Data, ResponseTimeout as Long)

Borland C++:

HRESULT MLXCommandAsync(/*[in,out]*/ TVariant* Data, /*[in]*/ long ResponseTimeout);

Microsoft Visual C++:

HRESULT MLXCommandAsync(/*[ref][out][in]*/ VARIANT* Data, /*[in]*/ long ResponseTimeout);

Parameters

Data

Address of VARIANT variable that holds the data to be sent and also receives the returned data. Depending on the function's returned value this can be an array of bytes or a long representing an operation cookie. In the latter case this value must be used when sinking OnReceivePacket event.

On return, if *Data is an array, it does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

ResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. *Data is of type VT_ARRAY | VT_UI1 and contains an array with the received data.

S_FALSE	The operation completed successfully but the request is still pending. *Data is of type VT_I4 and contains a valid cookie for the operation.

Any other error code	The operation failed. *Data is of type VT_I4 and contains zero.

Remarks

This method schedules the request and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case data is returned directly and OnReceivePacket event is not fired.

If the returned value is a valid cookie (not zero), it can be used to abort the operation with a call to CancelOperation method.

When the operation actually completes it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

MLXCommand, ChannelMLXCommand, ChannelMLXCommandAsync, OnReceivePacket


MLXReceive Method

Applies to: MPTChannel object.

Receives data synchronously. This method should be used to receive standard data packets from Melexis devices that support MPT communication protocol.

Syntax

Visual Basic:

Function MLXReceive(ResponseTimeout as Long)

Borland C++:

HRESULT MLXReceive(/*[in]*/ long ResponseTimeout, /*[out,retval]*/ TVariant* Data);

Microsoft Visual C++:

HRESULT MLXReceive(/*[in]*/ long ResponseTimeout, /*[retval][out]*/ VARIANT* Data);

Parameters

ResponseTimeout

A long specifying how much time, in ms, to wait for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Data

Address of VARIANT variable that receives the returned data. If the method succeeds it is an array of bytes (VT_ARRAY | VT_UI1), otherwise it is Empty (VT_EMPTY).

*Data does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

Return value

Visual Basic:

A Variant containing an array of bytes with the received data. It does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *Data contains valid data.

Any other error code	The operation failed. *Data is Empty (VT_EMPTY).

Remarks

This method does not return upon the completion of the operation. Before returning it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

MLXReceive first reads 1 or 3 bytes to determine how much bytes should receive.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Receive, ReceiveAsync, MLXReceiveAsync, ReceiveUntil, ReceiveUntilAsync


MLXReceiveAsync Method

Applies to: MPTChannel object.

Receives data asynchronously. This method should be used to receive standard data packets from Melexis devices that support MPT communication protocol.

Syntax

Visual Basic:

Function MLXReceiveAsync(ResponseTimeout as Long)

Borland C++:

HRESULT MLXReceiveAsync(/*[in]*/ long ResponseTimeout, /*[out,retval]*/ TVariant* Data);

Microsoft Visual C++:

HRESULT MLXReceiveAsync(/*[in]*/ long ResponseTimeout, /*[retval][out]*/ VARIANT* Data);

Parameters

ResponseTimeout

A long specifying how much time, in ms, to wait for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Data

Address of VARIANT variable that receives the returned data. Depending on the function's returned value this can be an array of bytes or a long representing an operation cookie. In the latter case this value must be used when sinking OnReceivePacket event.

NULL is not an acceptable value for this parameter. Clients should always expect the received data.

If *Data is an array, it does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

Return value

Visual Basic:

The return value must be interpreted according to its type:

Type	Meaning

Long	Represents a cookie for the operation, which is still pending. Data will be received via OnReceivePacket event. If the operation has failed the cookie is zero and the event should not be expected.

Array of bytes	Represents the received data. The operation has completed successfully. OnReceivePacket event will not be fired. The array does not include the leading 1 or 3 bytes from the packet which specify its size. The size can be retrieved from the array.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. *Data is of type VT_ARRAY | VT_UI1 and contains an array with the received data.

S_FALSE	The operation completed successfully but the request is still pending. *Data is of type VT_I4 and contains a valid cookie for the operation.

Any other error code	The operation failed. *Data is of type VT_I4 and contains zero.

Remarks

This method schedules the request and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case data is returned directly and OnReceivePacket event is not fired.

If the returned value is a valid cookie (not zero), it can be used to abort the operation with a call to CancelOperation method.

When the operation actually completes it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Receive, ReceiveAsync, MLXReceive, ReceiveUntil, ReceiveUntilAsync, OnReceivePacket


ModifyCustomCounter Method

Applies to: MPTChannel object.

Adds an integer value to the specified custom counter property. Creates the counter if it does not exist and initializes it with the provided value.

Syntax

Visual Basic:

Function ModifyCustomCounter(DeviceName as String, PropertyName as String, Addend as Long) as Long

Borland C++:

HRESULT ModifyCustomCounter(/*[in]*/ BSTR DeviceName,

                                                     /*[in]*/ BSTR PropertyName,

                                                     /*[in]*/ long Addend,

                                                     /*[out,retval]*/ long* pVal);

Microsoft Visual C++:

HRESULT ModifyCustomCounter(/*[in]*/ BSTR DeviceName,

                                                     /*[in]*/ BSTR PropertyName,

                                                     /*[in]*/ long Addend,

                                                     /*[retval][out]*/ long* pVal);

Parameters

DeviceName

A String specifying a device which owns the counter property.

PropertyName

A String specifying the name of the counter property.

Addend

A long specifying the value to be added to (or subtracted from, if it is negative) the counter property. Usually it is 1 or -1.

pVal

Address of long variable that receives the new value of the counter property.

Return value

Visual Basic:

A Long with the new value of the counter property.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains valid value.

S_FALSE	The operation completed successfully, but the counter property did not exist and was created. *pVal contains Addend.

Any other error code	The operation failed. *pVal is zero.

Remarks

Custom properties facilitate device objects in sharing their state and thereby allow multiple access to the channel.

Counter properties are always of type long. They are also accessible with their names via ReadCustomProperty and WriteCustomProperty methods.

The channel does not allow transition to negative values for the counter thereby avoiding underflow, which is an indication for an error in the calling module. However no error code is returned and the value of the counter becomes (or remains) 0.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReadCustomProperty, WriteCustomProperty


Quit Method

Applies to: CommManager object.

Frees all resources and prepares the module for unloading.

Syntax

Visual Basic:

Sub Quit()

Borland C++:

HRESULT Quit();

Microsoft Visual C++:

HRESULT Quit();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Normally MPT framework calls Quit as a part if its shutdown process. However, if another application has activated the module, it should call this method to avoid deadlocks and resource leaks.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


ReadBuffer Method

Applies to: MPTChannel object.

Reads data from the internal receiver's buffer of the channel.

Syntax

Visual Basic:

Function ReadBuffer(Index as Long, Count as Long)

Borland C++:

HRESULT ReadBuffer(/*[in]*/ long Index, /*[in]*/ long Count, /*[out,retval]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT ReadBuffer(/*[in]*/ long Index, /*[in]*/ long Count, /*[retval][out]*/ VARIANT* pVal);

Parameters

Index

A long specifying a zero based index in the buffer to start reading from.

Count

A long specifying the number of bytes to read.

pVal

Address of VARIANT variable that receives the data as an array of bytes. The caller is responsible for calling VariantClear on the variable when it is no longer needed.

Return value

Visual Basic:

An array of bytes. Its length may be smaller than Count if the receiver's buffer does not contain enough bytes.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid array of bytes.

S_FALSE	The operation completed successfully, but the receiver's buffer did not contain the requested number of bytes. *pVal contains a valid value, but the length of the array is smaller than Count.

Any other error code	The operation failed. *pVal contains zero.

Remarks

Index + Count must be from 0 to the value of BytesInBuffer.

Certain operations can clear the contents of the internal buffer, setting its capacity to zero.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


ReadCustomProperty Method

Applies to: MPTChannel object.

Returns the value of the specified custom property. If the property does not exist, it is created with the provided type and initialized with the provided value.

Syntax

Visual Basic:

Sub ReadCustomProperty(DeviceName as String, PropertyName as String, ByRef pVal)

Borland C++:

HRESULT ReadCustomProperty(/*[in]*/ BSTR DeviceName, /*[in]*/ BSTR PropertyName, /*[in,out]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT ReadCustomProperty(/*[in]*/ BSTR DeviceName, /*[in]*/ BSTR PropertyName, /*[ref][out][in]*/ VARIANT* pVal);

Parameters

DeviceName

A String specifying a device which owns the property.

PropertyName

A String specifying the name of the property.

pVal

Address of VARIANT variable that holds the initial value for the property and also receives the returned data. The method fails if the property already exists but its type differs from that provided in *pVal.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains valid data.

S_FALSE	The operation completed successfully, but the property did not exist and was created. *pVal remains unchanged.

Any other error code	The operation failed. *pVal is Empty (VT_EMPTY).

Remarks

Custom properties facilitate device objects in sharing their state and thereby allow multiple access to the channel.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

WriteCustomProperty, ModifyCustomCounter


Receive Method

Applies to: MPTChannel object.

Receives data synchronously.

Syntax

Visual Basic:

Function Receive(NrBytes as Long, ResponseTimeout as Long)

Borland C++:

HRESULT Receive(/*[in]*/ long NrBytes, /*[in]*/ long ResponseTimeout, /*[out,retval]*/ TVariant* Data);

Microsoft Visual C++:

HRESULT Receive(/*[in]*/ long NrBytes, /*[in]*/ long ResponseTimeout, /*[retval][out]*/ VARIANT* Data);

Parameters

NrBytes

A long specifying number of bytes to receive. If the internal receiver's buffer already contains the necessary information the method returns immediately.

ResponseTimeout

A long specifying how much time, in ms, to wait for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Data

Address of VARIANT variable that receives the returned data. If the method succeeds it is an array of bytes (VT_ARRAY | VT_UI1), otherwise it is Empty (VT_EMPTY).

Return value

Visual Basic:

A Variant containing an array of bytes with the received data.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *Data contains valid data.

Any other error code	The operation failed. *Data is Empty (VT_EMPTY).

Remarks

This method does not return upon the completion of the operation. Before returning it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReceiveAsync, ReceiveUntil, ReceiveUntilAsync, MLXReceive, MLXReceiveAsync


ReceiveAsync Method

Applies to: MPTChannel object.

Receives data asynchronously.

Syntax

Visual Basic:

Function ReceiveAsync(NrBytes as Long, ResponseTimeout as Long)

Borland C++:

HRESULT ReceiveAsync(/*[in]*/ long NrBytes, /*[in]*/ long ResponseTimeout, /*[out,retval]*/ TVariant* Data);

Microsoft Visual C++:

HRESULT ReceiveAsync(/*[in]*/ long NrBytes, /*[in]*/ long ResponseTimeout, /*[retval][out]*/ VARIANT* Data);

Parameters

NrBytes

A long specifying number of bytes to receive. If the internal receiver's buffer already contains the necessary information the method returns immediately.

ResponseTimeout

A long specifying how much time, in ms, to wait for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some data.

Data

Address of VARIANT variable that receives the returned data. Depending on the function's returned value this can be an array of bytes or a long representing an operation cookie. In the latter case this value must be used when sinking OnReceivePacket event.

NULL is not an acceptable value for this parameter. Clients should always expect the received data.

Return value

Visual Basic:

The return value must be interpreted according to its type:

Type	Meaning

Long	Represents a cookie for the operation, which is still pending. Data will be received via OnReceivePacket event. If the operation has failed the cookie is zero and the event should not be expected.

Array of bytes	Represents the received data. The operation has completed successfully. OnReceivePacket event will not be fired.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. *Data is of type VT_ARRAY | VT_UI1 and contains an array with the received data.

S_FALSE	The operation completed successfully but the request is still pending. *Data is of type VT_I4 and contains a valid cookie for the operation.

Any other error code	The operation failed. *Data is of type VT_I4 and contains zero.

Remarks

This method schedules a request for receiving and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case data is returned directly and OnReceivePacket event is not fired.

If the returned value is a valid cookie (not zero), it can be used to abort the operation with a call to CancelOperation method.

When the operation actually completes it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Receive, ReceiveUntil, ReceiveUntilAsync, MLXReceive, MLXReceiveAsync, OnReceivePacket


ReceiveUntil Method

Applies to: MPTChannel object.

Synchronously receives data upon the arrival of the provided sequence.

Syntax

Visual Basic:

Sub ReceiveUntil(ByRef Data, ResponseTimeout as Long)

Borland C++:

HRESULT ReceiveUntil(/*[in,out]*/ TVariant* Data, /*[in]*/ long ResponseTimeout);

Microsoft Visual C++:

HRESULT ReceiveUntil(/*[ref][out][in]*/ VARIANT* Data, /*[in]*/ long ResponseTimeout);

Parameters

Data

Address of VARIANT variable that holds the sequence that stops the receiving and also receives the returned data. If the method succeeds it is an array of bytes (VT_ARRAY | VT_UI1), otherwise it is Empty (VT_EMPTY).

ResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *Data contains valid data.

Any other error code	The operation failed. *Data is Empty (VT_EMPTY).

Remarks

This method does not return upon the completion of the operation. Before returning it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReceiveUntilAsync, Receive, ReceiveAsync, MLXReceive, MLXReceiveAsync


ReceiveUntilAsync Method

Applies to: MPTChannel object.

Asynchronously receives data upon the arrival of the provided sequence.

Syntax

Visual Basic:

Sub ReceiveUntilAsync(ByRef Data, ResponseTimeout as Long)

Borland C++:

HRESULT ReceiveUntilAsync(/*[in,out]*/ TVariant* Data, /*[in]*/ long ResponseTimeout);

Microsoft Visual C++:

HRESULT ReceiveUntilAsync(/*[ref][out][in]*/ VARIANT* Data, /*[in]*/ long ResponseTimeout);

Parameters

Data

Address of VARIANT variable that holds the sequence that stops the receiving and also receives the returned data. Depending on the function's returned value this can be an array of bytes or a long representing an operation cookie. In the latter case this value must be used when sinking OnReceivePacket event.

ResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. *Data is of type VT_ARRAY | VT_UI1 and contains an array with the received data.

S_FALSE	The operation completed successfully but the request is still pending. *Data is of type VT_I4 and contains a valid cookie for the operation.

Any other error code	The operation failed. *Data is of type VT_I4 and contains zero.

Remarks

This method schedules the request and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case data is returned directly and OnReceivePacket event is not fired.

If the returned value is a valid cookie (not zero), it can be used to abort the operation with a call to CancelOperation method.

When the operation actually completes it updates an internal index in the receiver's buffer, thereby preventing subsequent receive requests from reading the same data.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReceiveUntil, Receive, ReceiveAsync, MLXReceive, MLXReceiveAsync, OnReceivePacket


RegisterDevice Method

Applies to: MPTDevices object.

Puts another strong lock on the device object, thereby keeping it in memory.

Syntax

Visual Basic:

Function RegisterDevice(pVal as Object, FromScanning as Boolean) as Long

Borland C++:

HRESULT RegisterDevice(/*[in]*/ LPDISPATCH pVal, /*[in]*/ TOLEBOOL FromScanning, /*[out,retval]*/ long* plCookie);

Microsoft Visual C++:

HRESULT RegisterDevice(/*[in]*/ IDispatch* pVal, /*[in]*/ VARIANT_BOOL FromScanning, /*[retval][out]*/ long* plCookie);

Parameters

pVal

A pointer to an instance of IDispatch implementation.

FromScanning

Specifies the reason for registration:

Value	Meaning

True	Registration is performed as a part of the Scan procedure.

False	Registration is performed as a part of the ScanStandalone or any other procedure.

plCookie

A long specifying a device cookie. Each MPTDevice object has an associated cookie which is obtained with a call to RegisterDevice function. If the object has been already registered, this is the value which has been returned from the first invocation of this function.

Return value

Visual Basic:

A Long containing a device cookie.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully and the object was registered. *plCookie contains a valid device cookie.

S_FALSE	The operation completed successfully but the object has been already registered. *plCookie contains the cookie returned when the object was registered for the first time.

Any other error code	The operation failed. *plCookie contains zero.

Remarks

Usually MPTDevice objects automatically register and unregister themselves with the collection. This provides the MPT framework with information about currently activated devices.

Each successful call to RegisterDevice must be balanced by a subsequent call to UnregisterDevice.

Do not pass True for FromScanning parameter if not performing a standard Scan procedure.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

UnregisterDevice, ScanStandalone, Destroy


Reset Method

Applies to: PacketOperation object.

Clears any recorded operations with this object. All associated cookies are invalidated.

Syntax

Visual Basic:

Sub Reset()

Borland C++:

HRESULT Reset();

Microsoft Visual C++:

HRESULT Reset();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

AddOperation, Execute, ExecuteAsync


Save Method

Applies to: MPTChannel object.

Stores channel settings in the storage object.

Syntax

Visual Basic:

Sub Save(pStorage as Object)

Borland C++:

HRESULT Save(/*[in]*/ LPDISPATCH pStorage);

Microsoft Visual C++:

HRESULT Save(/*[in]*/ IDispatch* pStorage);

Parameters

pStorage

A pointer to an instance of IDispatch implementation of the storage object. It must implement IMPTStorage interface.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Load


Send Method

Applies to: MPTChannel object.

Sends data synchronously.

Syntax

Visual Basic:

Sub Send(Data)

Borland C++:

HRESULT Send(/*[in]*/ TVariantInParam Data);

Microsoft Visual C++:

HRESULT Send(/*[in]*/ VARIANT Data);

Parameters

Data

A VARIANT containing data to be sent. Can be a Byte, Integer, Long, an array of them or a String. If ti is a string, the terminating NULL character is not sent. The string is sent as ASCII characters, not UNICODE.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

This method does not return upon the completion of the operation.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SendAsync, ChannelSend, ChannelSendAsync


SendAsync Method

Applies to: MPTChannel object.

Sends data asynchronously.

Syntax

Visual Basic:

Function SendAsync(Data) as Long

Borland C++:

HRESULT SendAsync(/*[in]*/ TVariantInParam Data, /*[out,retval]*/ long* Cookie);

Microsoft Visual C++:

HRESULT SendAsync(/*[in]*/ VARIANT Data, /*[retval][out]*/ long* Cookie);

Parameters

Data

A VARIANT containing data to be sent. Can be a Byte, Integer, Long, an array of them or a String. If ti is a string, the terminating NULL character is not sent. The string is sent as ASCII characters, not UNICODE.

Cookie

Address of long variable that receives a cookie which identifies the operation. This value must be used when sinking OnSendComplete event.

You can pass NULL if completion notification is not needed and should not be fired. This improves the performance.

Return value

Visual Basic:

A Long representing a cookie which identifies the operation.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. If provided, *Cookie contains zero.

S_FALSE	The operation completed successfully but the request is still pending. If provided, *Cookie contains a valid cookie for the operation.

Any other error code	The operation failed. If provided, *Cookie contains zero.

Remarks

This method schedules a request for sending and returns immediately. However, it is possible the operation to complete before the returning of the method. In this case no cookie is returned even if Cookie parameter contains a valid pointer (actually zero is returned) and OnSendComplete event is not fired.

If the returned cookie is valid, it can be used to abort the operation with a call to CancelOperation method.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

Send, ChannelSend, ChannelSendAsync, OnSendComplete


SetBreak Method

Applies to: SerialChannel object.

Controls the state of the transmission line.

Syntax

Visual Basic:

Sub SetBreak(newVal as Boolean)

Borland C++:

HRESULT SetBreak(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT SetBreak(/*[in]*/ VARIANT_BOOL newVal);

Parameters

newVal

A Boolean specifying the new state of the transmission line - True - break state (transmission is stopped), False - normal state (characters are transmitted normally).

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SetRTS, SetDTR


SetDTR Method

Applies to: SerialChannel object.

Gives control over the DTR line.

Syntax

Visual Basic:

Sub SetDTR(newVal as Boolean)

Borland C++:

HRESULT SetDTR(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT SetDTR(/*[in]*/ VARIANT_BOOL newVal);

Parameters

newVal

A Boolean specifying the new state of the DTR line - True - ON state, False - OFF state.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SetRTS, SetBreak


SetRTS Method

Applies to: SerialChannel object.

Gives control over the RTS line.

Syntax

Visual Basic:

Sub SetRTS(newVal as Boolean)

Borland C++:

HRESULT SetRTS(/*[in]*/ TOLEBOOL newVal);

Microsoft Visual C++:

HRESULT SetRTS(/*[in]*/ VARIANT_BOOL newVal);

Parameters

newVal

A Boolean specifying the new state of the RTS line - True - ON state, False - OFF state.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

SetDTR, SetBreak


Synchronize Method

Applies to: MPTChannel object.

Synchronizes the calling thread with its associated request queue in the channel. The method schedules a marker request in the queue and waits for the marker to get back from the channel. This ensures that all requests from clients living in the calling thread have been handled.

Syntax

Visual Basic:

Sub Synchronize()

Borland C++:

HRESULT Synchronize();

Microsoft Visual C++:

HRESULT Synchronize();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


UnlockChannel Method

Applies to: MPTChannel object.

Releases a lock on the channel. The channel is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a channel it already owns.

This operation is synchronized through the associated request queue, however the method does not wait for its completion and returns immediately.

Syntax

Visual Basic:

Sub UnlockChannel()

Borland C++:

HRESULT UnlockChannel();

Microsoft Visual C++:

HRESULT UnlockChannel();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each successful call to LockChannel must be balanced by a subsequent call to UnlockChannel.

Calling this method without a previous successful call to LockChannel will generate an error.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

LockChannel


UnlockCollection Method

Applies to: MPTDevices object.

Releases a lock on the collection. The collection is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a collection it already owns.

This operation is synchronized through the associated request queue, however the method does not wait for its completion and returns immediately.

Syntax

Visual Basic:

Sub UnlockCollection()

Borland C++:

HRESULT UnlockCollection();

Microsoft Visual C++:

HRESULT UnlockCollection();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each successful call to LockCollection must be balanced by a subsequent call to UnlockCollection.

Calling this method without a previous successful call to LockCollection will generate an error.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in CommUnit.dll

See also

LockCollection


UnregisterDevice Method

Applies to: MPTDevices object.

Removes one strong lock from the specified device object.

Syntax

Visual Basic:

Sub UnregisterDevice(lCookie as Long)

Borland C++:

HRESULT UnregisterDevice(/*[in]*/ long lCookie);

Microsoft Visual C++:

HRESULT UnregisterDevice(/*[in]*/ long lCookie);

Parameters

lCookie

A long which specifies a device object cookie. It must exist in the collection in order to be eligible for unregistration.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The operation did not failed, but the specified device was not found in the collection.

Any other error code	The operation failed.

Remarks

A device is actually unregistered when its lock count reaches zero. After that it is not accessible for the MPT framework and only its COM reference count keeps it in memory.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

RegisterDevice, ScanStandalone, Destroy


WriteCustomProperty Method

Applies to: MPTChannel object.

Sets the value of the specified custom property. If the property does not exist, it is created with the provided type and initialized with the provided value.

Syntax

Visual Basic:

Sub WriteCustomProperty(DeviceName as String, PropertyName as String, newVal)

Borland C++:

HRESULT WriteCustomProperty(/*[in]*/ BSTR DeviceName, /*[in]*/ BSTR PropertyName, /*[in]*/ TVariantInParam newVal);

Microsoft Visual C++:

HRESULT WriteCustomProperty(/*[in]*/ BSTR DeviceName, /*[in]*/ BSTR PropertyName, /*[in]*/ VARIANT newVal);

Parameters

DeviceName

A String specifying a device which owns the property.

PropertyName

A String specifying the name of the property.

newVal

A VARIANT holding the new value for the property. The method fails if the property already exists but its type differs from that provided in newVal.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The operation completed successfully, but the property did not exist and was created.

Any other error code	The operation failed.

Remarks

Custom properties facilitate device objects in sharing their state and thereby allow multiple access to the channel.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

ReadCustomProperty, ModifyCustomCounter


OnDelayComplete Event

Applies to: MPTChannel object.

Confirms the completion of an asynchronous delay operation, scheduled by a call to DelayAsync method.

Syntax

Visual Basic:

Event OnDelayComplete(Hash as Long, Cookie as Long, stat as ChannelStatus)

Borland C++:

void OnDelayComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Microsoft Visual C++:

void OnDelayComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Parameters

Hash

A long specifying a hash value which identifies the channel throughout the system.

Cookie

A long specifying an operation cookie.

stat

A value from ChannelStatus enumeration specifying completion code for the operation.

Remarks

This event is not fired for synchronous operations and for delay operations inside packet operations.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


OnDestroy Event

Applies to: MPTChannel object.

Informs the client that the channel is about to be destroyed. The client must release all references to the channel including associated packet operations.

Syntax

Visual Basic:

Event OnDestroy(Hash as Long)

Borland C++:

void OnDestroy(/*[in]*/ long Hash);

Microsoft Visual C++:

void OnDestroy(/*[in]*/ long Hash);

Parameters

Hash

A long specifying a hash value which identifies the channel that needs to be released.

Remarks

Usually this event is fired from a process, that hosts a remote channel and needs to close. All clients should release their references to the channel thus ensuring proper termination of the process and avoiding resource leaks.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


OnError Event

Applies to: MPTChannel object.

Informs the client that an error has occurred.

Syntax

Visual Basic:

Event OnError(Hash as Long, Cookie as Long, ec as ErrorCode, Param1 as Long, Param2 as Long)

Borland C++:

void OnError(/*[in]*/ long Hash,

                      /*[in]*/ long Cookie,

                      /*[in]*/ ErrorCode ec,

                      /*[in]*/ long Param1,

                      /*[in]*/ long Param2);

Microsoft Visual C++:

void OnError(/*[in]*/ long Hash,

                      /*[in]*/ long Cookie,

                      /*[in]*/ ErrorCode ec,

                      /*[in]*/ long Param1,

                      /*[in]*/ long Param2);

Parameters

Hash

A long specifying the hash value of the channel reporting the error. This is the value of the channel's HashValue property.

Cookie

A long specifying an operation cookie. Note that synchronous operations also generate and use cookies internally.

ec

A value from ErrorCode enumeration describing the error.

Param1 and Param2

long values which provide additional error information.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


OnPacketOperationComplete Event

Applies to: MPTChannel object.

Confirms the completion of an asynchronous packet operation, scheduled by a call to ExecuteAsync method.

Syntax

Visual Basic:

Event OnPacketOperationComplete(Hash as Long, Cookie as Long, stat as ChannelStatus)

Borland C++:

void OnPacketOperationComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Microsoft Visual C++:

void OnPacketOperationComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Parameters

Hash

A long specifying a hash value which identifies the channel throughout the system.

Cookie

A long specifying an operation cookie.

stat

A value from ChannelStatus enumeration specifying completion code for the whole packet operation.

Remarks

This event is not fired for synchronous packet operations.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll

See also

PacketOperation


OnReceivePacket Event

Applies to: MPTChannel object.

Confirms the completion of an asynchronous receive operation. ReceiveAsync, ReceiveUntilAsync, MLXReceiveAsync and MLXCommandAsync methods use this event to provide the received data to the client. Packet operations also fire OnReceivePacket event.

Syntax

Visual Basic:

Event OnReceivePacket(Hash as Long, Data, Cookie as Long, stat as ChannelStatus)

Borland C++:

void OnReceivePacket(/*[in]*/ long Hash, /*[in]*/ TVariantInParam Data, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Microsoft Visual C++:

void OnReceivePacket(/*[in]*/ long Hash, /*[in]*/ VARIANT Data, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Parameters

Hash

A long specifying a hash value which identifies the channel throughout the system.

Data

A VARIANT holding the received data. It is valid only if stat is csOK.

Cookie

A long specifying an operation cookie.

stat

A value from ChannelStatus enumeration specifying completion code for the operation.

Remarks

This event is not fired for synchronous operations.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


OnSendComplete Event

Applies to: MPTChannel object.

Confirms the completion of an asynchronous send operation, scheduled by a call to SendAsync method.

Syntax

Visual Basic:

Event OnSendComplete(Hash as Long, Cookie as Long, stat as ChannelStatus)

Borland C++:

void OnSendComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Microsoft Visual C++:

void OnSendComplete(/*[in]*/ long Hash, /*[in]*/ long Cookie, /*[in]*/ ChannelStatus stat);

Parameters

Hash

A long specifying a hash value which identifies the channel throughout the system.

Cookie

A long specifying an operation cookie.

stat

A value from ChannelStatus enumeration specifying completion code for the operation.

Remarks

This event is not fired for synchronous operations and for send operations inside packet operations.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


OnSettingsChanged Event

Applies to: MPTChannel object.

Informs the client that the channel settings have changed.

Syntax

Visual Basic:

Event OnSettingsChanged(Hash as Long)

Borland C++:

void OnSettingsChanged(/*[in]*/ long Hash);

Microsoft Visual C++:

void OnSettingsChanged(/*[in]*/ long Hash);

Parameters

Hash

A long specifying a hash value which identifies the channel.

Quick Info

Header: Declared in CommUnit.h.

Module: Implemented in CommUnit.dll


ChannelType Enumeration

Description

ChannelType enumeration defines constants for different kinds of channels. Multiple flags can be combined by using the bitwise OR operator.

Definition

The following is a list of the ChannelType constants

Constant	Description

ctAll	Represents all types of channels. For use with EnumChannels and EnumChannelsStr methods.

ctSerial	Represents a serial channel.

ctParallel	Represents a parallel channel.

ctUSB	Represents a USB channel.

ctIrDA	Represents an IrDA channel.

Additional constants may be added in the future.

Quick Info

Header: Declared in CommUnit.h.


FlushFlags Enumeration

Description

FlushFlags enumeration defines constants for identification of the internal buffers of a channel when they have to be cleared.

Definition

The following is a list of the FlushFlags constants

Constant	Description

ffSender	Refers to the buffer of the sender part.

ffReceiver	Refers to the buffer of the receiver part.

ffBoth	Refers to both sender's and receiver's channels.

Quick Info

Header: Declared in CommUnit.h.


MPTCRC Enumeration

Description

MPTCRC enumeration defines constants for specifying the CRC algorithm applied on the data, flowed through the channel.

Definition

The following is a list of the MPTCRC constants

Constant	Description

crcNone	No CRC calculation will be applied.

crc255	Specifies 8-bit check sum with feedback of the carry flag to the LSB.

crcLINMaster	Specifies Melexis LINMaster specific check sum. It is not valid for Melexis USB LinMaster device.

Quick Info

Header: Declared in CommUnit.h.


MPTIrDAService Enumeration

Description

MPTIrDAService enumeration defines constants for use with IrDA channels.

Definition

The following is a list of the MPTIrDAService constants

Constant	Description

MPT_IrSrvcUnknown	Specifies an invalid service.

MPT_IrCOMM_9wire	Specifies IrCOMM 9-wire service on TinyTP protocol.

MPT_IrCOMM_3wire	Specifies IrCOMM 3-wire service on TinyTP protocol (not supported).

MPT_IrCOMM_3raw	Specifies IrCOMM 3-wire raw service (not supported).

MPT_OBEX	Specifies OBEX service (not supported).

MPT_IrLPT	Specifies IrLPT service (not supported).

MPT_IrNetv1	Specifies IrNetv1 service (not supported).

MPT_IrLAN	Specifies IrLAN service (not supported).

Additional constants may be added in the future.

Quick Info

Header: Declared in CommUnit.h.


OperationCodes Enumeration

Description

OperationCodes enumeration defines constants for use with packet operations.

Definition

The following is a list of the OperationCodes constants

Constant	Description

ocSend	Specifies a send command.

ocReceive	Specifies a receive command.

ocMLXReceive	Specifies a MLXReceive command.

ocMLXCommand	Specifies a MLXCommand command.

ocDelay	Specifies a delay command.

ocFlush	Specifies a flush command.

Quick Info

Header: Declared in CommUnit.h.


SerialBaudRates Enumeration

Description

SerialBaudRates enumeration defines constants for use with BaudRate property and EnsureConnected method.

Definition

The following is a list of the SerialBaudRates constants

Constant	Description

br110	Specifies baud rate of 110 bps.

br300	Specifies baud rate of 300 bps.

br600	Specifies baud rate of 600 bps.

br1200	Specifies baud rate of 1200 bps.

br2400	Specifies baud rate of 2400 bps.

br4800	Specifies baud rate of 4800 bps.

br9600	Specifies baud rate of 9600 bps.

br14400	Specifies baud rate of 14400 bps.

br19200	Specifies baud rate of 19200 bps.

br38400	Specifies baud rate of 38400 bps.

br56000	Specifies baud rate of 56000 bps.

br57600	Specifies baud rate of 57600 bps.

br115200	Specifies baud rate of 115200 bps.

br128000	Specifies baud rate of 128000 bps.

br256000	Specifies baud rate of 256000 bps.

Quick Info

Header: Declared in CommUnit.h.


SerialDataBits Enumeration

Description

SerialDataBits enumeration defines constants for use with DataBits property and EnsureConnected method.

Definition

The following is a list of the SerialDataBits constants

Constant	Description

DB4	Use 4 data bits.

DB5	Use 5 data bits.

DB6	Use 6 data bits.

DB7	Use 7 data bits.

DB8	Use 8 data bits.

Quick Info

Header: Declared in CommUnit.h.


SerialFlowControl Enumeration

Description

SerialFlowControl enumeration defines constants for serial handshaking.

Definition

The following is a list of the SerialFlowControl constants

Constant	Description

fcNone	No handshaking is applied.

fcHarware	Hardware handshaking is applied. RTS/CTS and DTR/DSR pins control the flow of data.

fcSoftware	Software handshaking is applied. Xon and Xoff characters control the flow of data.

Quick Info

Header: Declared in CommUnit.h.


SerialParity Enumeration

Description

SerialParity enumeration defines constants for use with Parity property and EnsureConnected method.

Definition

The following is a list of the SerialParity constants

Constant	Description

NoParity	Do not use parity.

OddParity	Use odd parity.

EvenParity	Use even parity.

MarkParity	Use mark parity.

SpaceParity	Use space parity.

Quick Info

Header: Declared in CommUnit.h.


SerialPortNumber Enumeration

Description

SerialPortNumber enumeration defines constants for serial ports identification.

Definition

The following is a list of the SerialPortNumber constants

Constant	Description

COM1	Refers to the first serial port, usually COM1.

COM2	Refers to the second serial port, usually COM2.

COM3	Refers to the third serial port, usually COM3, if it exists.

COM4	Refers to the fourth serial port, usually COM4, if it exists.

COM5	Refers to the fifth serial port, usually COM5, if it exists.

COM6	Refers to the sixth serial port, usually COM6, if it exists.

COM7	Refers to the seventh serial port, usually COM7, if it exists.

COM8	Refers to the eighth serial port, usually COM8, if it exists.

Quick Info

Header: Declared in CommUnit.h.


SerialStopBits Enumeration

Description

SerialStopBits enumeration defines constants for use with StopBits property and EnsureConnected method.

Definition

The following is a list of the SerialStopBits constants

Constant	Description

OneStopBit	Use 1 stop bit.

One5StopBits	Use 1.5 stop bits.

TwoStopBits	Use 2 stop bits.

Quick Info

Header: Declared in CommUnit.h.


Object Model
Common objects

The common objects:

Object	Represents

MPTCollection	Basic collection object.

MPTProgressCallback	A client implemented object, receiving callbacks at certain events

MPTRevisionInfo	Provides revision information for the derived objects

ObjectCollection	A collection of objects.

The object hierarchy:

MPTCollection

MPTProgressCallback (implemented in the client software when necessary)

MPTRevisionInfo

ObjectCollection (creatable with ProgID "MPT.ObjectCollection" and CLSID_ObjectCollection)


MPTCollection Object

The MPTCollection object defines basic collection functionality. It cannot be created directly, however each derived collection object can be casted safely to MPTCollection.

The object is compatible with For Each .. Next Visual Basic statement, which allows a convenient iteration over the members of the collection.

Properties

Item

Count


MPTProgressCallback Object

The MPTProgressCallback object defines functionality for getting progress information for some long lasting communication processes. It is exposed by the client software and implements IMPTProgressCallback interface. A reference to such an object can then be passed as an argument to a long lasting method.

Methods

OnStart

OnProgress

OnEnd


MPTRevisionInfo Object

The MPTRevisionInfo object defines the functionality for obtaining revision information of a software module. It cannot be created directly, but can safely be casted from the objects implementing IMPTRevisionInfo interface.

Methods

CheckRevision

GetAssetName

GetModuleRevision


ObjectCollection Object

The ObjectCollection object implements a collection of references to Automation objects. It derives from MPTCollection object and therefore implements basic collection functionality.

Methods

AddObject

FindObject

LockCollection

RemoveAll

RemoveObject

UnlockCollection


Count Property

Applies to: MPTCollection object.

Gets the count of the collection members.

Syntax

Visual Basic:

Property Count as Long

Read only

Borland C++:

HRESULT get_Count(/*[out, retval]*/ long* pVal);

Microsoft Visual C++:

HRESULT get_Count(/*[out, retval]*/ long* pVal);

Parameters

pVal

Address of a long variable that receives the count of the members.

Return value

Visual Basic:

Current size of the collection.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid number.

Any other error code	The operation failed. *pVal contains 0.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

Item


Item Property

Applies to: MPTCollection object.

Returns a specific collection member.

Syntax

Visual Basic:

Property Item(Index) as Variant

Read only

Borland C++:

HRESULT get_Item(/*[in]*/ TVariantInParam Index, /*[out,retval]*/ TVariant* pVal);

Microsoft Visual C++:

HRESULT get_Item(/*[in]*/ VARIANT Index, /*[out, retval]*/ VARIANT* pVal);

Parameters

Index

A VARIANT specifying the index of the member. Usually, this is a numeric value, which is a zero based index in the collection. Some collections also allow a string to be used, which is interpreted as a member's name. Therefore, passing a string representation of a number may generate an error in certain situations.

pVal

Address of a VARIANT variable that receives the required member. It may be of type VT_EMPTY if an error has occurred or the member was not found.

Return value

Visual Basic:

The required collection member. It may be Empty if an error has occurred or the member was not found.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid value.

S_FALSE	The operation did not failed, but the member was not found in the collection. *pVal contains VT_EMPTY.

Any other error code	The operation failed. *pVal contains VT_EMPTY.

Remarks

Visual Basic:

The Item property is the default property for a collection. Therefore, the following lines of code are equivalent:

Channels(1).Connected = True

Channels.Item(1).Connected = True

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

Count


AddObject Method

Applies to: ObjectCollection object.

Adds a new object to the collection..

Syntax

Visual Basic:

Sub AddObject(pObj as Object)

Borland C++:

HRESULT AddObject(/*[in]*/ LPDISPATCH pObj);

Microsoft Visual C++:

HRESULT AddObject(/*[in]*/ IDispatch* pObj);

Parameters

pObj

A pointer to an instance of IDispatch implementation to be added to the collection.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The object already exists in the collection.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

RemoveObject


ChannelMLXCommand Function

Applies to: Global shared function. Does not belong to any object.

Synchronously executes a command sequence. This function is an optimized wrapper for MLXCommand method. It directly calls the channel bypassing unnecessary VARIANT creation and destruction.

Syntax

C++:

HRESULT WINAPI ChannelMLXCommand(/*[in]*/ IDispatch* pChan,

                                                            /*[in]*/ const unsigned char* pData,

                                                            /*[in,out]*/ long* pcbSize,

                                                            /*[out]*/ unsigned char** ppResult,

                                                            /*[in]*/ long lResponseTimeout);

Parameters

pChan

A pointer to an instance of IDispatch implementation of a channel object.

pData

A pointer to a buffer containing data to be sent. It can be allocated in any way and should be freed by the caller.

pcbSize

A pointer to long variable that specifies the size in bytes of pData buffer. On return this variable holds the size of *ppResult buffer or zero if an error occurs.

ppResult

An address of long pointer which receives the address of the buffer with the returned data. It is NULL if an error occurs.

The caller is responsible to free the memory when it is no longer needed with a call to LocalFree function.

The buffer does not contain the leading 1 or 3 bytes which specify the size of the packet.

lResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some unread data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppResult and *pcbSize contain valid data.

Any other error code	The operation failed. *ppResult contains NULL and *pcbSize contains zero.

Remarks

Refer to MLXCommand method for more information.

Quick Info

Header: Declared in MPTHelpers.h.

Module: Implemented in MLXMPT.dll

See also

ChannelMLXCommandAsync


ChannelMLXCommandAsync Function

Applies to: Global shared function. Does not belong to any object.

Asynchronously executes a command sequence. This function is an optimized wrapper for MLXCommandAsync method. It directly calls the channel bypassing unnecessary VARIANT creation and destruction.

Syntax

C++:

HRESULT WINAPI ChannelMLXCommandAsync(/*[in]*/ IDispatch* pChan,

                                                                      /*[in]*/ const unsigned char* pData,

                                                                      /*[in,out]*/ long* pcbSize,

                                                                      /*[out]*/ unsigned char** ppResult,

                                                                      /*[in]*/ long lResponseTimeout);

Parameters

pChan

A pointer to an instance of IDispatch implementation of a channel object.

pData

A pointer to a buffer containing data to be sent. It can be allocated in any way and should be freed by the caller.

pcbSize

A pointer to long variable that specifies the size in bytes of pData buffer. On return this variable holds the size of *ppResult buffer or zero if an error occurs.

ppResult

An address of BYTE pointer which receives the address of the buffer with the returned data (without the leading 1 or 3 bytes) or a four bytes long buffer, containing an operation cookie if the operation is still pending. In the latter case *pcbSize is 4.

*ppResult is NULL if an error occurs, otherwise the caller is responsible to free the memory when it is no longer needed with a call to LocalFree function.

lResponseTimeout

A long specifying how much time, in ms, to wait after sending for the first byte to arrive before signaling a timeout. The channel applies its own timeout settings after the first byte has been received.

This value is ignored if the internal receiver's buffer already contains some data.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *ppResult contains the received data and *pcbSize contains the size of the data.

S_FALSE	The operation completed successfully but the request is still pending. *ppResult contains an operation cookie and *pcbSize is 4. The data should be received via OnReceivePacket event.

Any other error code	The operation failed. *ppResult contains NULL and *pcbSize contains zero.

Remarks

Refer to MLXCommandAsync method for more information.

Quick Info

Header: Declared in MPTHelpers.h.

Module: Implemented in MLXMPT.dll

See also

ChannelMLXCommand


ChannelSend Function

Applies to: Global shared function. Does not belong to any object.

Sends data synchronously. This function is an optimized wrapper for Send method. It directly calls the channel bypassing unnecessary VARIANT creation and destruction.

Syntax

C++:

HRESULT WINAPI ChannelSend(/*[in]*/ IDispatch* pChan,

                                              /*[in]*/ const unsigned char* pData,

                                              /*[in]*/ long cbSize);

Parameters

pChan

A pointer to an instance of IDispatch implementation of a channel object.

pData

A pointer to a buffer containing data to be sent. It can be allocated in any way and should be freed by the caller.

cbSize

A long variable that specifies the size in bytes of pData buffer.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Refer to Send method for more information.

Quick Info

Header: Declared in MPTHelpers.h.

Module: Implemented in MLXMPT.dll

See also

ChannelSendAsync


ChannelSendAsync Function

Applies to: Global shared function. Does not belong to any object.

Sends data asynchronously. This function is an optimized wrapper for SendAsync method. It directly calls the channel bypassing unnecessary VARIANT creation and destruction.

Syntax

C++:

HRESULT WINAPI ChannelSendAsync(/*[in]*/ IDispatch* pChan,

                                                       /*[in]*/ const unsigned char* pData,

                                                       /*[in]*/ long cbSize,

                                                       /*[out]*/ long* plCookie);

Parameters

pChan

A pointer to an instance of IDispatch implementation of a channel object.

pData

A pointer to a buffer containing data to be sent. It can be allocated in any way and should be freed by the caller.

cbSize

A long variable that specifies the size in bytes of pData buffer.

plCookie

Address of long variable that receives a cookie which identifies the operation. This value must be used when sinking OnSendComplete event.

You can pass NULL if completion notification is not needed and should not be fired. This improves the performance.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation and request completed successfully. If provided, *plCookie contains zero.

S_FALSE	The operation completed successfully but the request is still pending. If provided, *plCookie contains a valid cookie for the operation.

Any other error code	The operation failed. If provided, *Cookie contains zero.

Remarks

Refer to SendAsync method for more information.

Quick Info

Header: Declared in MPTHelpers.h.

Module: Implemented in MLXMPT.dll

See also

ChannelSend


CheckRevision Method

Applies to: MPTRevisionInfo object

This method fills in an array of AssetInfo records. Each module in the chain must add asset names of other modules that it depends on, then call their GetModuleRevision and GetAssetName functions and put these values into corresponding AssetInfo entries and finally must call CheckRevision functions of the other downstream modules, if applicable and if the modules are loaded.

Syntax

Visual Basic:

Function CheckRevision(parray() As AssetInfo, pnCount As Long, [nLevel As Long = 1]) As Boolean

Borland C++:

HRESULT CheckRevision(/*[in,out]*/ LPSAFEARRAY* parray,

    /*[in,out]*/ int* pnCount,

    /*[in,def,opt]*/ int nLevel,

    /*[out,retval]*/ TOLEBOOL* pvbRes);

Microsoft Visual C++:

HRESULT CheckRevision(/*[out][in]*/ LPSAFEARRAY* parray,

    /*[out][in]*/ int* pnCount,

    /*[defaultvalue][in]*/ int nLevel,

    /*[retval][out]*/ VARIANT_BOOL* pvbRes);

Parameters

parray

An address of a SAFEARRAY of AssetInfo records pointer variable, where the collected information is stored. The caller is responsible to release the occupied memory when not in use, by calling SafeArrayDestroy.

pnCount

An address of a Long variable that specifies the first index in the array, where the collected information will be put. On exit it must contain the index of the next available element.

nLevel

A Long, specifying the current depth level.

pvbRes

An address of a VARIANT_BOOL variable that receives an overall result of the downstream check - TRUE if all the dependencies meet the requirements, or FALSE otherwise.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.


FindObject Method

Applies to: ObjectCollection object.

Search for the presence of the specified object in the collection.

Syntax

Visual Basic:

Function FindObject(pObj as Object) as Boolean

Borland C++:

HRESULT FindObject(/*[in]*/ LPDISPATCH pObj, /*[out,retval]*/ TOLEBOOL* pVal);

Microsoft Visual C++:

HRESULT FindObject(/*[in]*/ IDispatch* pObj, /*[retval][out]*/ VARIANT_BOOL* pVal);

Parameters

pObj

A pointer to an instance of IDispatch implementation to search for.

pVal

Address of Boolean variable that receives the result of the search - True - the object exists in the collection, False - the object was not found in the collection.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in PSF module.


GetAssetName Method

Applies to: MPTRevisionInfo object

Gets the asset name of the corresponding object. This name is unique for the software module that object belongs to.

Syntax

Visual Basic:

Function GetAssetName as String

Borland C++:

HRESULT GetAssetName(/*[out, retval]*/ BSTR* pVal);

Microsoft Visual C++:

HRESULT GetAssetName(/*[retval][out]*/ BSTR* pVal);

Parameters

pVal

Address of BSTR variable that receives the asset name of the object. If the invocation succeeds, the caller is responsible for calling SysFreeString on the variable when it is no longer needed.

Return value

Visual Basic:

A String representing the asset name of the object.

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pVal contains a valid string.

Any other error code	The operation failed. *pVal contains NULL.

Quick Info

Header: Declared in MLXMPT.h.


GetModuleRevision Method

Applies to: MPTRevisionInfo object

Gets the revision numbers of the software module that object belongs to.

Syntax

Visual Basic:

Sub GetModuleRevision(pMajor As Long, pMinor As Long)

Borland C++:

HRESULT GetModuleRevision(/*[out]*/ long *pMajor, /*[out]*/ long *pMinor);

Microsoft Visual C++:

HRESULT GetModuleRevision(/*[out]*/ long *pMajor, /*[out]*/ long *pMinor);

Parameters

pMajor

Address of a Long variable that receives the major part of the revision of the module.

pMinor

Address of a Long variable that receives the minor part of the revision of the module.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully. *pMajor and *pMinor contain valid numbers.

Any other error code	The operation failed. *pMajor and *pMinor contain 0.

Quick Info

Header: Declared in MLXMPT.h.


LockCollection Method

Applies to: MPTCollection object.

Attempts to gain an exclusive access to the collection. A locked collection serves only requests scheduled from its owner thread. All other requests remain in their queues until the collection is unlocked.

Syntax

Visual Basic:

Sub LockCollection()

Borland C++:

HRESULT LockCollection();

Microsoft Visual C++:

HRESULT LockCollection();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

The calling thread is blocked until the collection confirms that it is owned by the thread.

Each successful call to LockCollection must be balanced by a subsequent call to UnlockCollection. The collection is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a collection it already owns.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

UnlockCollection


MPTMustActivateLowerLayers Method

Applies to: Global shared function. Does not belong to any object.

This function is called during object activation.

MPT Framework calls Activate method for top level objects (usually DASUIModule objects) and they are responsible for the activation of the objects in the lower layers. The activation parameter passed from the framework specifies whether to activate the lower layers or not. Also it contains information for the activation of this object.

Syntax

C++:

HRESULT WINAPI MPTMustActivateLowerLayers(/*[in][out]*/ VARIANT& vParam,

                                                                              /*[out]*/ VARIANT& vMyParam,

                                                                        /*[out]*/ bool& bResult);

Parameters

vParam

A reference to VARIANT variable which holds the activation parameter passed from the framework or the upper object. On return this variable is modified and contains the activation parameter for the object at the next level.

vMyParam

A reference to VARIANT variable which receives the activation information for this object. It is interpreted individually for each object.

bResult

A reference to bool variable which receives information about the activation of the next level. If it is true, this object must call Activate method of the next level object before activating itself.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MPTHelpers.h.

Module: Implemented in MLXMPT.dll

See also

Activate


OnEnd Method

to be added


OnProgress Method

to be added


OnStart Method

to be added


RemoveAll Method

Applies to: ObjectCollection object.

Empties the collection.

Syntax

Visual Basic:

Sub RemoveAll()

Borland C++:

HRESULT RemoveAll();

Microsoft Visual C++:

HRESULT RemoveAll();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll


RemoveObject Method

Applies to: ObjectCollection object.

Deletes the specified object from the collection.

Syntax

Visual Basic:

Sub RemoveObject(pObj as Object)

Borland C++:

HRESULT RemoveObject(/*[in]*/ LPDISPATCH pObj);

Microsoft Visual C++:

HRESULT RemoveObject(/*[in]*/ IDispatch* pObj);

Parameters

pObj

A pointer to an instance of IDispatch implementation to be removed from the collection.

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

S_FALSE	The object does not exist in the collection.

Any other error code	The operation failed.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

AddObject


UnlockCollection Method

Applies to: MPTCollection object.

Releases a lock on the collection. The collection is actually unlocked when its lock count reaches zero. The lock count prevents the thread from blocking itself while trying to lock a collection it already owns.

This operation is synchronized through the associated request queue, however the method does not wait for its completion and returns immediately.

Syntax

Visual Basic:

Sub UnlockCollection()

Borland C++:

HRESULT UnlockCollection();

Microsoft Visual C++:

HRESULT UnlockCollection();

Return value

C++:

The return value obtained from the returned HRESULT is one of the following:

Return value	Meaning

S_OK	The operation completed successfully.

Any other error code	The operation failed.

Remarks

Each successful call to LockCollection must be balanced by a subsequent call to UnlockCollection.

Calling this method without a previous successful call to LockCollection will generate an error.

Quick Info

Header: Declared in MLXMPT.h.

Module: Implemented in MLXMPT.dll

See also

LockCollection


ChannelStatus Enumeration

Description

ChannelStatus enumeration defines constants for identification of the results of execution of a channel operation.

Definition

The following is a list of the ChannelStatus constants

Constant	Description

csOK	No error.

csTimeOut	Timeout has occurred.

csAborted	The operation was aborted.

csNotConnected	The channel is not connected.

csFileError	An error occurred while working with a file.

csPending	The operation is still pending.

csResources	Insufficient resources.

csUnspecified	A general error, which cannot be classified to any of the above categories.

Additional constants may be added in the future.

Quick Info

Header: Declared in MLXMPT.h.


DeviceType Enumeration

Description

DeviceType enumeration defines constants for different kinds of devices. Multiple flags can be combined by using the bitwise OR operator.

Definition

The following is a list of the DeviceType constants

Constant	Description

dtAll	Represents all types of devices.

dtSerial	Represents a serial device.

dtParallel	Represents a parallel device.

dtUSB	Represents a USB device.

dtIrDA	Represents an IrDA device.

Additional constants may be added in the future.

Quick Info

Header: Declared in MLXMPT.h.


ErrorCode Enumeration

Description

ErrorCode enumeration defines constants for error identification.

Definition

The following is a list of the ErrorCode constants

Constant	Description

ecNoError	No error.

ecMemory	Insufficient memory.

ecChannel	The channel has generated an error.

ecBadParam	Invalid parameter.

ecOSError	An error from the operating system.

ecUnspecified	A general error has occurred, which cannot be classified to any of the above categories.

Additional constants may be added in the future.

Quick Info

Header: Declared in MLXMPT.h.


AssetInfo Record

Description

AssetInfo record type holds a piece of information, collected during the process of walking through the revision dependencies of software modules. The result of CheckRevision method of MPTRevisionInfo object is an array of such records.

Definition

The following is the definition of AssetInfo record type:

Visual Basic:

Type AssetInfo

nLevel 	as Long

szRequiredModule 	as String

lRequiredRevisionMajor 	as Long

lRequiredRevisionMinor 	as Long

szPresentModule 	as String

lCurrentRevisionMajor 	as Long

lCurrentRevisionMinor 	as Long

nResult 	as Long

End Type

C++:

struct AssetInfo

{

int 	nLevel;

BSTR 	szRequiredModule;

long 	lRequiredRevisionMajor;

long 	lRequiredRevisionMinor;

BSTR 	szPresentModule;

long 	lCurrentRevisionMajor;

long 	lCurrentRevisionMinor;

int 	nResult;

};

Members

nLevel

A Long specifying the depth level of the information within the record in the whole hierarchy of dependencies.

szRequiredModule

A String specifying the name of a required module.

lRequiredRevisionMajor

A Long specifying the major part of the revision of a required module.

lRequiredRevisionMinor

A Long specifying the minor part of the revision of a required module.

szPresentModule

A String containing the actual name got from the required module.

lCurrentRevisionMajor

A Long containing the major part of the revision got from the required module.

lCurrentRevisionMinor

A Long containing the minor part of the revision got from the required module.

nResult

A Long containing the result of comparsion of required and present name and revision.

Quick Info

Header: Declared in MLXMPT.h.