mbustcpmasterprotocol.pas

ModBus Communications Libraries for Delphi

(**
 * @internal
 * @file MbusTcpMasterProtocol.pas
 *
 * @if NOTICE
 *
 * $Id: MbusTcpMasterProtocol.pas,v 1.8 2005/07/25 22:41:01 henrik Exp $
 *
 * Copyright (c) 2003-2005 FOCUS Software Engineering Pty Ltd, Australia.
 * All rights reserved. <www.focus-sw.com>
 *
 * USE OF THIS SOFTWARE IS GOVERNED BY THE TERMS AND CONDITIONS OF A
 * SEPARATE LICENSE STATEMENT AND LIMITED WARRANTY.
 *
 * IN PARTICULAR, YOU WILL INDEMNIFY AND HOLD FOCUS SOFTWARE ENGINEERING,
 * ITS RELATED COMPANIES AND ITS SUPPLIERS, HARMLESS FROM AND AGAINST ANY
 * CLAIMS OR LIABILITIES ARISING OUT OF THE USE, REPRODUCTION, OR
 * DISTRIBUTION OF YOUR PROGRAMS, INCLUDING ANY CLAIMS OR LIABILITIES
 * ARISING OUT OF OR RESULTING FROM THE USE, MODIFICATION, OR DISTRIBUTION
 * OF PROGRAMS OR FILES CREATED FROM, BASED ON, AND/OR DERIVED FROM THIS
 * SOURCE CODE FILE.
 *
 * @endif
 *)


unit MbusTcpMasterProtocol;


(*****************************************************************************
 * Interface
 *****************************************************************************)

interface

uses
   Classes,
   MbusMasterFunctions;


(*****************************************************************************
 * MbusTcpMasterProtocol class declaration
 *****************************************************************************)

(**
 * MODBUS/TCP Master Protocol class
 *
 * This class realises the MODBUS/TCP master protocol. It provides
 * functions to establish and to close a TCP/IP connection to the slave as
 * well as data and control functions which can be used after a connection
 * to a slave device has been established successfully. The data and
 * control functions are organized different conformance classes. For a
 * more detailed description of the data and control functions see section
 * @ref mbusmaster.
 *
 * It is also possible to instantiate multiple instances of this class for
 * establishing multiple connections to either the same or different hosts.
 *
 * @ingroup mbusmastertcp
 * @version 1.1
 * @see mbusmaster
 * @see TMbusMasterFunctions
 *)
type
   TMbusTcpMasterProtocol = class(TMbusMasterFunctions)

    protected

      fHostName: string;


    public

      constructor Create(aOwner: TComponent); override;

      (**
       * @name TCP/IP Connection Management Functions
       *)
      //@{

      function openProtocol(): Integer;

      procedure setPort(portNo: word);

      function getPort: word;


    published

      (**
       * Host name property (eg "127.0.0.1")
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property hostName: string read fHostName write fHostName;

      (**
       * TCP port property (eg 502)
       *
       * @note A protocol must be closed in order to configure it.
       * @remark Usually the port number remains unchanged and defaults to
       * 502. However if the port number has to be different from 502
       * this property must be called <i>before</i> opening the
       * connection with openProtocol().
       *)
      property port: word read getPort write setPort default 502;

      //@}

   end;

procedure Register;


(*****************************************************************************
 * Implementation
 *****************************************************************************)

implementation

uses
   BusProtocolExceptions;


(*****************************************************************************
 * DLL stub functions
 *****************************************************************************)

function mbusMaster_createTcpProtocol: pointer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_createTcpProtocol@0';

function mbusMaster_openTcpProtocol(mbusHdl: pointer;
                                    hostName : pwidechar): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_openTcpProtocol@8';

function mbusMaster_setTcpPort(mbusHdl: pointer; portNo : word): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_setTcpPort@8';

function mbusMaster_getTcpPort(mbusHdl: pointer): word;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getTcpPort@4';


(*****************************************************************************
 * MbusTcpMasterProtocol class implementation
 *****************************************************************************)

(**
 * @defgroup mbusmastertcp MODBUS/TCP Protocol
 *
 * The MODBUS/TCP master protocol is implemented in the class
 * MbusTcpMasterProtocol. It provides functions to establish and to close a
 * TCP/IP connection to the slave as well as data and control functions
 * which can be used after a connection to a slave device has been
 * established successfully. The data and control functions are organized
 * different conformance classes. For a more detailed description of the
 * data and control functions see section @ref mbusmaster.
 *
 * Using multiple instances of a MbusTcpMasterProtocol class enables
 * concurrent protocol transfers using multiple TCP/IP sessions (They should
 * be executed in separate threads).
 *
 * See section @ref mbustcpprotocol for some background information about
 * MODBUS/TCP.
 *
 * See section @ref tcpintegrate for an example how to use the
 * MbusTcpMasterProtocol class.
 *)
//@{
//@}


(**
 * Constructs a TMbusTcpMasterProtocol object and initialises its data.
 *
 * @exception EOutOfResources Creation of class failed
 *)
constructor TMbusTcpMasterProtocol.Create(aOwner: TComponent);
begin
   inherited Create(aOwner);
   mbusHdl := mbusMaster_createTcpProtocol;
   if mbusHdl = nil then
      raise EOutOfResources.Create('Instanciation of protocol object failed!');
   fHostName := '127.0.0.1';
end;


(**
 * Connects to a MODBUS/TCP slave.
 *
 * This function establishes a logical network connection between master
 * and slave. After a connection has been established data and control
 * functions can be used. A TCP/IP connection should be closed if it is no
 * longer needed.
 *
 * @note The default TCP port number is 502.
 * @exception EInOutError An I/O error occurred
 * @exception EOpenErr The port could not be opened
 * @exception EPortNoAccess No permission to access port
 * @exception ETcpipConnectErr TCP/IP connection error, host not reachable
 * @exception EConnectionWasClosed Remote peer closed TCP/IP connection
 * @exception EIllegalArgumentError A parameter is invalid
 *)
function TMbusTcpMasterProtocol.openProtocol(): Integer;
//var
//   result: integer;
begin
   result := mbusMaster_openTcpProtocol(mbusHdl, pwidechar(widestring(fHostName)));
//   if result <> 0 then
//      raise exceptionFactory(result);
end;


(**
 * Sets the TCP port number to be used by the protocol.
 *
 * @remark Usually the port number remains unchanged and defaults to
 * 502. In this case no call to this function is necessary. However if
 * the port number has to be different from 502 this function must be
 * called <i>before</i> opening the connection with openProtocol().
 *
 * @param portNo Port number to be used when opening the connection
 * @exception EIllegalStateError Protocol is already open
 * @exception EIllegalArgumentError A parameter is out of range
 *)
procedure TMbusTcpMasterProtocol.setPort(portNo: word);
var
   result: integer;
begin
   result := mbusMaster_setTcpPort(mbusHdl, portNo);
   if result <> 0 then
      raise exceptionFactory(result);
end;


(**
 * Returns the TCP port number used by the protocol.
 *
 * @return Port number used by the protocol
 *)
function TMbusTcpMasterProtocol.getPort: word;
begin
   getPort := mbusMaster_getTcpPort(mbusHdl);
end;


(**
 * Registers component
 *)
procedure Register;
begin
  RegisterComponents('FieldTalk', [TMbusTcpMasterProtocol]);
end;


end.