rtcconn.pas

Delphi快速开发Web Server

    { DataIn event,
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerDataIn; virtual;
    // @exclude
    procedure CallDataIn; virtual;

    { LastWrite event,
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerLastWrite; virtual;
    // @exclude
    procedure CallLastWrite; virtual;

    { DataSent event,
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerDataSent; virtual;
    // @exclude
    procedure CallDataSent; virtual;
    // @exclude
    procedure CallReadyToSend; virtual;

    { DataReceived event,
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerDataReceived; virtual;
    // @exclude
    procedure CallDataReceived; virtual;

    { DataLost event (used by UDP only),
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerDataLost; virtual;
    // @exclude
    procedure CallDataLost; virtual;

    { Exception event,
      ready to be mapped to a connection provider's trigger.
      @exclude }
    procedure TriggerException(E:Exception); virtual;
    // @exclude
    procedure CallException(E:Exception); virtual;

    { Called to raise exceptions
      @exclude }
    procedure Error(Err:string);

    { Used by the Timeout component to trigger an internal disconnect,
      which will result in a reconnect, if reconnect parameters are set.
      @exclude }
    procedure InternalDisconnect; virtual;

    // @exclude
    function InsideEvent:boolean;

    { This event will be triggered every time this connection component's
      buffer is completely empty and the other side has just become ready to
      accept new data. It is good to wait for this event before starting
      to send data out, even though you can start sending data directly
      from the @Link(OnConnect) event.
      @html(<br><br>)

      By responding to this event and sending the data only after it was
      triggered, you avoid keeping the data in the send buffer, especially
      if the data you are sending is being read from a file on disk,
      which wouldn't occupy any memory until loaded. }
    property OnReadyToSend:TRtcNotifyEvent read FOnReadyToSend write FOnReadyToSend;
    { This event will be triggered every time a chunk of your data
      prepared for sending has just been sent out. To know
      exactly how much of it is on the way, use the @Link(DataOut) property.
      @html(<br><br>)

      NOTE: Even though data has been sent out, it doesn't mean that
      the other side already received it. It could also be that connection will
      break before this package reaches the other end. }
    property OnDataOut:TRtcNotifyEvent read FOnDataOut write FOnDataOut;
    { This event will be triggered every time a chunk of data
      has just come in (received). To know exactly how much of it
      has just arrived, use the @Link(DataIn) property. }
    property OnDataIn:TRtcNotifyEvent read FOnDataIn write FOnDataIn;
    { This event will be triggered when all data prepared for sending
      has been sent out and the sending buffer has become empty again.
      @html(<br><br>)

      When sending large data blocks, try slicing them in small chunks,
      sending a chunk at a time and responding to this event to prepare
      and send the next chunk. This will keep your memory needs low. }
    property OnDataSent:TRtcNotifyEvent read FOnDataSent write FOnDataSent;
    { When this event triggers, it means that the other side has sent you
      some data and you can now read it. Check the connection component's
      description to see which properties and methods you can use
      to read the data received. }
    property OnDataReceived:TRtcNotifyEvent read FOnDataReceived write FOnDataReceived;

  public

    { DO NOT CALL THIS CONSTRUCTOR DIRECTLY!!!
      Use the 'NEW' class function to create a new object!!! }
    constructor Create(AOwner:TComponent); override;

    { DO NOT CALL THIS DESTRUCTOR DIRECTLY!!!
      DO NOT CALL 'FREE' DIRECTLY!!!
      Use the @Link(Release) method to destroy this object. }
    destructor Destroy; override;

    { Is this Server connection running as an extension or a plug-in to another app (ISAPI or CGI)?
      This property is used internaly by some components, to determine
      how internal things (like delayed calls) need to be processed. }
    function isExtension:boolean; virtual;

    { Needs to be called by connection components to signalize
      that component is entering a state where a user-defined
      event will be called. This is to prevent users from
      destroying the connection component from inside an event
      handler and to handle the Disconnect, Connect, Relase and
      other methods that affect connection status.
      @exclude }
    procedure EnterEvent; virtual;

    { Needs to be called by connection components to signalize
      that component is leaving a state where a user-defined
      event was called. This is to prevent users from
      destroying the connection component from inside an event
      handler and to handle the Disconnect, Connect, Relase and
      other methods that affect connection status.
      @exclude }
    procedure LeaveEvent; virtual;

    { If you create connection components at runtime,
      allways use the 'NEW' class function to create the connection
      object and 'RELEASE' procedure to free the connection object.
      @html(<br><br>)

      To make the code you write compatible with all new versions of Delphi,
      and to make sure that object is not released while it is still being used
      by internal connection component mechanisms,
      ONLY USE this 'Release' procedure to free any connection component and
      release all the resources that are used by the component.
      @html(<br><br>)

      After calling Release, you should also set the variable to NIL,
      in which you have stored the connection component. }
    procedure Release; virtual;

    { All native RTC connection components know when they get
      disconnected from peer and also trigger the events required.
      @html(<br><br>)

      But, there may be some third-party connection components coming,
      which will not know when a connection was closed by peer
      (for example, different implementations of blocking TCP/IP).
      @html(<br><br>)

      The @name method is here to cover such cases and give the connection
      provider means to write a method for checking if the connection is
      still active. In such cases, after calling the Check procedure,
      if the connection is still active, nothing will happen. But if the
      connection is dead, connection will be closed by the connection provider. }
    procedure Check; virtual;

    { *1.) If this is a listening connection,
      stop listening and close all connections open to this listener (gracefuly).
      All events that need to be triggered will be triggered.
      @html(<br><br>)

      *2.) If this is a client connection (initiated by this or the other side),
      close the connection (gracefuly).
      All events that need to be triggered will be triggered. }
    procedure Disconnect; virtual;

    { Is the connection in the process of closing (disconnecting)?
      Do not try to send any more data out if this is @true. }
    function isClosing:boolean; virtual;

    { Get this connection's Peer Address (to which Address/IP are we connected?) }
    function PeerAddr:string; virtual;

    { Get this connection's Peer Port (to which Port are we connected?) }
    function PeerPort:string; virtual;

    { Get this connection's Local Address (on which local IP are we?) }
    function LocalAddr:string; virtual;

    { Get this connection's Local Port (on which local Port are we?) }
    function LocalPort:string; virtual;

    { Return the total number of active connections, counting all connections that
      are opened to this process by any TRtcConnection class (all servers and clients). }
    function TotalConnectionCount:integer; virtual;

    { Return the number of active connections,
      open by our Client connection components. }
    function TotalClientConnectionCount:integer; virtual;

    { Return the number of active connections,
      open to our Servers connection components. }
    function TotalServerConnectionCount:integer; virtual;

    { Post a job to connection thread's job queue.
      @param(Job
      - If using existing connection components (not extenting them),
      'Job' object has to be of @Link(TRtcJob) type,
      or else the 'Unknown Job' exception will be raised
      from within the thread, which will close the connection. }
    function PostJob(Job:TObject; HighPriority:boolean=False):boolean; virtual;

    { Pause all connection operations (works only if @Link(MultiThreaded) is True). }
    function Pause:boolean;

    { Resume connection operations (works only if @Link(MultiThreaded) is True). }
    function Resume:boolean;

    { Call this procedure to signal connection that you
      have just started processing received data.
      When you start processing data, it means that
      you have received at least one whole data package.
      @html(<br><br>)

      Knowing this, thread pooling can better utilize
      thread usage, allowing other connections to
      start reading/writing data. }
    procedure Processing;

    { Call the 'Event' synchronized (from the Mail Thread).
      You have to use this method to call events which want to access
      the GUI (Graphical User Interface: everything visual).
      To check wether your event is being executed from inside the
      Main Thread, use the connection's @Link(inMainThread) function.
      @param(Event - TRtcNotifyEvent method to be called synchronized, from the Main Thread.)
      @return(@True if the call was succesful) }
    function Sync(Event:TRtcNotifyEvent):boolean; overload; virtual;

    { Same as Sync(Event), with a difference that you
      can synchronize @Link(TRtcErrorEvent) events with this call
      and 'Err' will be used as the Exception parameter when
      calling the 'Event'.
      @param(Event - TRtcErrorEvent method to be called synchronized, from the MainThread)
      @param(Err - Exception object to be passed to the event)
      @return(@True if the call was succesful) }
    function Sync(Event:TRtcErrorEvent; Err:Exception):boolean; overload; virtual;

    { Same as Sync(Event), with a difference that you
      can synchronize @Link(TRtcFunctionCallEvent) events with this call
      and 'Param' and 'Res' will be passed as parameters when calling the 'Event'.
      @param(Event - TRtcFunctionCallEvent method to be called synchronized, from the MainThread)
      @param(Par - TRtcFunctionCall object, containing all function call information)
      @param(Res - TRtcValue object, ready to receive the result information)
      @return(@True if the call was succesful) }
    function Sync(Event:TRtcFunctionCallEvent; Par:TRtcFunctionInfo; Res:TRtcValue):boolean; overload; virtual;

    { Same as Sync(Event), with the difference that you
      can synchronize @Link(TRtcResultEvent) events with this call
      and 'Res' will be passed as the result parameter when calling the 'Event'.
      @param(Event - TRtcFunctionCallEvent method to be called synchronized, from the MainThread)
      @param(Data - TRtcValue object, containing the information which was sent to the server, which has produced the "Res")
      @param(Res - TRtcValue object, containing the result information)
      @return(@True if the call was succesful) }
    function Sync(Event:TRtcResultEvent; Data:TRtcValue; Res:TRtcValue):boolean; overload; virtual;

    { Call the 'Event' synchronized (from the Main Thread).
      You have to use this method to call events which want to access
      the GUI (Graphical User Interface: everything visual).
      To check wether your event is being executed from inside the
      Main Thread, use the connection's @Link(inMainThread) function.
      @param(Event - TRtcUserEvent method to be called synchronized, from the Main Thread.)
      @param(Obj - Object to be passed as parameter to the event)
      @return(@True if the call was succesful) }
    function Sync(Event:TRtcUserEvent; Obj:TObject):boolean; overload; virtual;

    { You can use this method to check if you are inside the Main thread,
      from which drawing and writing to the GUI is allowed. If true,
      you can directly access the GUI. If false, you have to use the
      Sync() method to call this or some other event synchronized,
      from where you can use the drawing routines. }
    function inMainThread:boolean; virtual;

    { You can use this method to check if your connection object is currently
      inside its Thread. If true, jobs do not have to be posted,
      they can be called directly. To check if you are allowed to
      access GUI (drawing or writing to the screen or canvas),
      use the @Link(inMainThread) function. }
    function inThread:boolean; virtual;

    { Read function is used to read data received. It may ONLY be called
      from inside your @Link(OnDataReceived) event handler.
      Its behavior depends on the connection component that implements it. }
    function Read:string; virtual;
    { Write function is used to send data out.
      Its behavior depends on the connection component that implements it. }
    procedure Write(const s:string=''); virtual;

    { @name (Read-Only) can be used from the @Link(OnDataOut) event,
      to check how much data has now been sent out. The value of this
      property changes with every @Link(OnDataOut) event and should
      only be read from your @Link(OnDataOut) event handler. }
    property DataOut:cardinal read FDataOut;

    { @name (Read-Only) can be used from the @Link(OnDataIn) event,
      to check how much data has just arrived. The value of this
      property changes with every @Link(OnDataIn) event and should
      only be read from your @Link(OnDataIn) event handler. }
    property DataIn:cardinal read FDataIn;

    { Total number of bytes read from the other side (Peer/Remote) through this connection. }