2. Ocit-c Protocol v1 r1

download 2. Ocit-c Protocol v1 r1

of 38

Transcript of 2. Ocit-c Protocol v1 r1

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    1/38

    O C I T D e v e l o p e r G r o u p ( O D G ) & P a r t n e rOCIT

    Registered trade mark of Dambach, Siemens, Signalbau Huber, Stoye, Sthrenberg

    Open Communication Interface for Road Traffic Control Systems

    Offene Schnittstellen fr die Straenverkehrstechnik

    OCIT-C Center to Center

    Transportation Protocol

    OCIT-C_Protocol_V1_R1

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    2/38

    OCIT-C_Protocol_V1_R1 Page 2 of 38

    OCIT-C Center to Center

    Transportation Protocol

    Document: OCIT-C_Protocol_V1_R1

    Author: OCIT Developer Group (ODG) & Partner (Schlothauer&Wauer, PTV)

    www.ocit.org

    Copyright 2010 ODG & Partner.All rights reserved.Documents with versions or issue conditions with

    newer date replace all contents of preceding versions.

    http://../AppData/AppData/Local/Microsoft/Windows/Workshops/13.Workshop_Juni_08/Vorbereitung/Original/www.ocit.orghttp://../AppData/AppData/Local/Microsoft/Windows/Workshops/13.Workshop_Juni_08/Vorbereitung/Original/www.ocit.orghttp://../AppData/AppData/Local/Microsoft/Windows/Workshops/13.Workshop_Juni_08/Vorbereitung/Original/www.ocit.org
  • 8/12/2019 2. Ocit-c Protocol v1 r1

    3/38

    OCIT-C_Protocol_V1_R1 Page 3 of 38

    Contents Page

    1 Introduction .....................................................................................................................51.1 History of Change .....................................................................................................51.2 Definitions.................................................................................................................5 1.3 Abbrevations .............................................................................................................5

    2 Transfer Protocol Soap ....................................................................................................62.1 Technology ...............................................................................................................62.2 Protocol Requirements ..............................................................................................62.3 Concept and Security ................................................................................................62.4 Protocol functions .....................................................................................................7

    2.4.1 Reading data by a Client ..............................................................................72.4.2 Send data to server ......................................................................................9

    2.5 Sequence Control .................................................................................................... 102.5.1 Data Buffering and position handling ......................................................... 112.5.2 Too long transaction time .......................................................................... 112.5.3 Too long inquiriesl ..................................................................................... 122.5.4 Handle historical data access ...................................................................... 132.5.5 Multi client capability................................................................................. 132.5.6 Resynchronisation ...................................................................................... 142.5.7 Bidirectional communication ...................................................................... 16

    2.5.7.1 Bidirectional communication sequences with Client&Server pair ................ 162.5.7.1.1 Switching a sign (sequences) ................................................................ 16

    2.5.7.2 Bidirectional communication sequences polling current state ...................... 202.5.7.2.1 Switching a sign (sequence) .................................................................. 20

    2.6 OSI Layering ........................................................................................................ 212.7 Protocol Functions in Detail .................................................................................... 22

    2.7.1 getContentInfo .......................................................................................... 24

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    4/38

    OCIT-C_Protocol_V1_R1 Page 4 of 38

    2.7.2 get ............................................................................................................. 242.7.3 inquireAll................................................................................................... 272.7.4 put ............................................................................................................. 292.7.5 delete......................................................................................................... 302.7.6 Parameters ................................................................................................. 31

    3 Data structures ............................................................................................................... 324 How to Use .............................................................. Fehler! Textmarke nicht definiert.

    4.1 Data delivery interface / one or more Consumer ...................................................... 324.2 Configuration Interface ........................................................................................... 334.3 Interface between Central Units to update its data (unidirectional) ........................... 344.4 Interface between Central Units to update its data (bidirectional) ............................. 35

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    5/38

    OCIT-C_Protocol_V1_R1 Page 5 of 38

    11 IInnttrroodduuccttiioonnThe communication between Central Units and communication interfaces to these Central

    Units should be implemented unique in all Central Units.

    As an approach the communication interface Soap can be used. The Soap protocol is thecommon communication interface over them all communications are done. This communica-

    tion interface is called OCIT-C.

    These interfaces are declared to be open. Therefore they can be used by external systems.

    The task of this document is to describe this open protocol and its usage.

    It is not the task of this document to describe data structures of the particular data.

    11..11 HHiissttoorryyooffCChhaannggee

    Version

    State

    Date Recipients Name Change

    V1.0 E01 03.03.2010 ODG&Partner

    DKE 713.3.4

    M. Senninger Draft

    V1.0 A01 02.06.2010 PUBLIC M. Senninger Preliminary version

    V1 R1 02.09.2010 PUBLIC M.Senninger First version

    11..22 DDeeffiinniittiioonnss

    Statement Definition

    SOAP Simple Object Access Protocol. Transfers commands with the means of XMLby using httpIt is described withinhttp://www.w3.org/TR/SOAP.

    Protocolmanager Protocollayer which implements commands and the buffer.SoapServer-Interface

    Includes Soap and ProtocolManager at the server site

    SoapClient-Interface

    Includes Soap and ProtocolManager at the client site

    11..33 AAbbbbrreevvaattiioonnss

    Abbrevation DescriptionSSL Secure Socket Layer.

    http://www.w3.org/TR/SOAPhttp://www.w3.org/TR/SOAPhttp://www.w3.org/TR/SOAPhttp://www.w3.org/TR/SOAP
  • 8/12/2019 2. Ocit-c Protocol v1 r1

    6/38

    OCIT-C_Protocol_V1_R1 Page 6 of 38

    22 TTrraannssffeerrPPrroottooccoollSSooaappThis chapter describes the Soap interface.

    22..11 TTeecchhnnoollooggyy

    Data is encoded with XML. This includes the following advantages:

    usable protocol for all components (no dependency on used data)

    tracable

    plattform independency.

    easy expandable.

    The protocol includes easy commands like write, get or delete. FTP is not sufficient.

    As transfer media

    SOAP on the base of http is used

    Soap itself uses XML to build its data.

    22..22 PPrroottooccoollRReeqquuiirreemmeennttss

    data are represented as XML data at the output interface.

    data are accepted as XML at the input interface (configuration)

    commands are embedded within XML. (e.g. post,get)

    objects are identified by external identifiers.

    one cannot mix different object types within one request

    protocol is stateless within the server. This means that the server does not know any-thing about the client.

    22..33 CCoonncceeppttaannddSSeeccuurriittyy

    The protocol is a client server protocol.

    Security will be implemented by using username and password in plain text.

    Three classes of unintended foreign accesses:

    The aggressor uses the transmission link to intrude into the computer (client or server),for example to steal or modify data.This scenario is the most frequent (and the most severe

    in terms of the consequences). To put a stop to this under TCP/IP, it is necessary for only one

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    7/38

    OCIT-C_Protocol_V1_R1 Page 7 of 38

    port at most to be enabled towards the outside and for this port not to be a default port. In the

    protocol described above (with http as the underlying layer), a firewall for the client can be

    made so restrictive that no connections can be opened towards the clients and only one specific

    port is opened out to the control centre. The best possible protection for the client is provided

    with a suitably configured firewall. In this case, SOAP is not configured to port 80, but to a

    project-specific port number.The control centre can also be fairly reliably protected by i) not installing SOAP to port 80 in

    the specific project and ii) by implementing SOAP via its own classes and not via the IIS.

    The aggressor attempts to gain access to SOAP to execute OCIT commands there as an

    OCIT client.(This scenario does not call for a particularly trained aggressor.) In this scenario,

    the aggressor does not even attempt to reach default ports and is not even able to steal data or

    to manipulate files. Such an attack is also only suitable for the server (and not for the client).

    Such an attack is relatively simple, but is made practically impossible by the user name and the

    password, provided the attacker is not aware of a valid pair.

    The (professional) aggressor intercepts a TCP connection and determines a user name

    and password (professionals only). This scenario does not permit any theft either and also no

    file manipulation, but does allow the aggressor to pretend to be an OCIT client without know-

    ing a password and user name. You have to do a cost/benefit calculation here. As it is not quite

    easy, except for specialists, to intercept and read a TCP connection, the data really ought to be

    interesting enough to make such a break-in worthwhile. To circumvent this, an HTTPS con-

    nection can be used with moderate effort instead of an http connection (this entails additional

    programming effort because SSL libraries have to be incorporated) and, when using Verisign,

    for example, a public key has to be requested for the control centre and has to be paid for,

    unless communication partners agree on a self-generating key and enter it manually. In such a

    case, it is practically no longer possible to intercept and read a connection between the clientand the control centre. In my opinion, though, such a changeover is not worth the effort.

    The server saves a list of user names and their associated passwords. The server also stores

    details of which operations are permitted by which user. Access from more than one client is

    possible with the same name, with the result that not all clients have to be made known in the

    server.

    22..44 PPrroottooccoollffuunnccttiioonnss

    With the protocol you are able to read and configure data. Besides it is possible evaluate ob-jects and instances concerning availability and structure dynamicly during runtime.

    Every command consists of a request and a response.

    Executing a request a XML structure is transfered from Client to the Server, The result of the

    call is put into a Result (also called a response structure) and sent back to the client.

    22..44..11 RReeaaddiinnggddaattaabbyyaaCClliieenntt

    All protocol functions to read data include a filter as parameter. This filter is a field of objectswhich are to be read. In case the filter is empty all objects will be returned in any other case

    only those objects included in the filter list.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    8/38

    OCIT-C_Protocol_V1_R1 Page 8 of 38

    In order to ease the resynchronisation a last start information is added to each response of a

    read access With this information the client is able to decide when to resynchronise (in case of

    changed start string).

    The server offers all readable data at its outer interface. The server offers data of several object

    types.The Client is able to query all available object types with the command getContentInfo.

    Those objecttypes which are contained in the answere can be read by the Client (if the client

    has read access to it). either by the protocol function get or inquireAll

    The difference between inquireAll and get is as follows:

    .InquireAll delivers all objects of the requested object type with the last state/contents of the

    objects. It has to be used in any case of resynchronisation (e.g. restart of the server or the cli-

    ent).

    The function get delivers changes since last time having requested the server. This mechanism

    is described in detail within chapter2.5.1 Data Buffering and position handling.

    The following sequences shows how data is requested from server periodicly with the help of

    the protocol functions inquireAll (resynchronisation function) and get (function to read deltas

    since last having requested).

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    9/38

    OCIT-C_Protocol_V1_R1 Page 9 of 38

    Soap-

    Client-I

    Soap-

    Server-I

    Data-

    Base

    Data

    inquireAll

    inquireAll-

    ResponseNow theclient knows all objects

    of the requested object

    type

    Data

    Data

    Data

    Data

    Data

    Data

    get

    getResponse

    Now the

    client knows all changes

    since last request

    get

    Soap-

    Client-I

    Soap-

    Server-I

    Data-

    Base

    get

    getResponse

    Figure 1: Usual Sequence to Read Data From SoapserverInterface

    22..44..22 SSeennddddaattaattoosseerrvveerr

    It is possible to send data to the server. The protocol function put is to be used for this pur-

    pose.

    The behaviour of the Server depends on the object type, In case of unknown objects in the putcommand, either the object will be created or an error will be returned. To delete objects the

    command delete is required

    The configuration interface is rather simple using the command put. The configuration data can

    be placed into it and is to be sent towards the server. The server accepts it or rejects all uncon-

    figurable objects in the putResult-list.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    10/38

    OCIT-C_Protocol_V1_R1 Page 10 of 38

    Soap-

    Client-I

    Soap-

    Server-I

    Data-

    Base

    put

    put-

    Response

    Data

    Data

    put

    put-

    Response

    Soap-

    Client-I

    Soap-

    Server-I

    Data-

    Base

    Now the

    client knows about

    successfull configured

    objects and errors

    Now theclient knows about

    successfull configured

    objects and errors

    Figure 2: Usual Sequence to Write/Configure Data to the SoapserverInterface

    22..55 SSeeqquueenncceeCCoonnttrrooll

    The protocol is connection less. To achieve sequence control it is sufficient to wait for the

    response of the according request. This is achieved by http. So no additional sequence control

    is required.

    Nevertheless some special hints should be obeyed. Those sequences are described in the fol-

    lowing chapters.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    11/38

    OCIT-C_Protocol_V1_R1 Page 11 of 38

    22..55..11 DDaattaaBBuuffffeerriinnggaannddppoossiittiioonnhhaannddlliinngg

    Figure 3: Data buffering at server side and position handling at client side

    The server buffer provides data in a data buffer. The buffer is a short term buffer. This buffer

    should be organised as a ring buffer supplying client requests from its data base.

    After executing an inquireAll the client knows the last state from the data base. Besides the

    inquireAll-Response the client receives the last position number, indicating the last information

    from server (pointer to last received data in the data buffer). With the help of this position

    number the client issues the next server request (get). With the help of the position number, the

    server knows which date has to be provided to obtain all changes, occurred since last clients

    request. The get response includes the data and a new position number, which is to be used for

    the next get request of the client.

    22..55..22 TToooolloonnggttrraannssaaccttiioonnttiimmee

    Usually the response carries the requested data. In case the server requires longer than ac-

    ceptabable (rec. > 60s), an empty response will be returned to the client. The exceeded trans-action time will be indicated by an own error code. However the server continues to obtain the

    data from its data base (or archive).

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    12/38

    OCIT-C_Protocol_V1_R1 Page 12 of 38

    The client will repeat its request after a certain time. After this time the server is able to supply

    the data (because organised in background). If not the server indicates the too long transaction

    time again.

    Soap-

    Client-I

    Soap-

    Server-I

    Data-

    Base

    inquireAll

    inquireAllResponse

    (error=too long time)

    Soap-Client-I

    Soap-Server-I

    Data-Base

    data access

    data

    access

    requires

    time

    data access

    returns data

    inquireAll

    inquireAllResponse

    (data, pos. number)

    wa

    itingtime

    Figure 4: Handle long transaction time (similar sequence for get requests)

    22..55..33 TToooolloonnggiinnqquuiirriieessll

    The server returns an error code, in case the contents of a responseexceeds a threshold.

    This may happen, in case

    Too many historical data is requested (time range too big)

    Too many deltas since last requested

    Too many objects requested

    The client has to reduce its request accordingly.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    13/38

    OCIT-C_Protocol_V1_R1 Page 13 of 38

    22..55..44 HHaannddlleehhiissttoorriiccaallddaattaaaacccceessss

    The command get is used, in case access to historical data is required.

    The element storetime is used to define the start in the historical store.

    The element endstore is used to define the end in the historical storage.

    The get-response will contain date from storetime to endStore in consequence.

    It is recommended to

    Keep time ranges as small as possible (chapter2.5.3 Too long inquiriesl)

    React on possible to long reaction time (chapter2.5.3 Too long inquiriesl)

    Use object filters (limit amount of objects)

    22..55..55 MMuullttiicclliieennttccaappaabbiilliittyy

    The server works sessionless. The position number avoids building up any knowledge about

    the client at the server side.

    Implementing OCIT-C, just obey that the used lower layer libraries should allow multiple client

    access.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    14/38

    OCIT-C_Protocol_V1_R1 Page 14 of 38

    22..55..66 RReessyynncchhrroonniissaattiioonn

    There might be different reasons for resynchronisation:

    Client restart

    client knows about his start

    client has to resynchronise data with inquireAll

    server possibly recognises client restart with the help of the watch dog

    (watchdog is optional !)

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    15/38

    OCIT-C_Protocol_V1_R1 Page 15 of 38

    Server restart

    client possibly recognises unavailable server (socket timeout)

    or

    server responds any protocol function (inquireAll, get or put) including last-

    Start, which indicates the time whe server started last time

    the client has to resynchronise with inquireAll in case this lastStart differs frompreviously responded lastStart

    Soap-Client-I

    Soap-Server-I

    Soap::inquireAll

    get-Response

    The client recognisesserver restart with modified

    lastStat in get response

    Soap-Client-I

    Soap-Server-I

    get

    Serverrestart

    get-Response

    get

    getClient recognises serverrestart with socket error

    inquireAll-Response

    get-Response

    get

    get-Response

    get

    s

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    16/38

    OCIT-C_Protocol_V1_R1 Page 16 of 38

    22..55..77 BBiiddiirreeccttiioonnaallccoommmmuunniiccaattiioonn

    The following use cases require communication in both directions:

    Intersection control:- switch command is transferred from central 1 to central 2

    - current state (not the requested command !) is send in the other direction and asyn-

    chronously from central 2 to central 1

    CCTV- PTZ (pan/til/zoom) command is transferred from central 1 to central 2

    - current state (not the requested command !) is send in the other direction and asyn-

    chronously from central 2 to central 1

    Sign control- sign switch command is transferred from central 1 to central 2

    - current state and content (not the requested content !) is send in the other direction

    and asynchronously from central 2 to central 1

    The following chapters describe possible approaches. Sign control is used as an example. Bidi-

    rectional communication for other use cases work in a similar way.

    22..55..77..11 BBiiddiirreeccttiioonnaallccoommmmuunniiccaattiioonnsseeqquueenncceesswwiitthhCClliieenntt&&SSeerrvveerrppaaiirr

    2.5.7.1.1 Switching a sign (sequences)

    The following transmission is used for signs.

    2.5.7.1.1.1 Switching a sign (good case)The following image describes the sequence to issue put commands (good case):

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    17/38

    OCIT-C_Protocol_V1_R1 Page 17 of 38

    Soap-

    Client-I

    Soap-

    Server-I

    put (Sign Switch

    Command)

    Soap::put-

    Result

    Soap-Client-I Soap-Server-I

    Soap-

    Client-I

    Soap-Server-I

    Soap-

    Server-I

    Soap-Server-I

    forward switch to

    application

    switch command to the

    interface

    put (Sign Switch State-o.k./content information)

    Soap::put-

    Result

    change state

    too.k.(successful

    switch

    command)

    change state

    to o.k.

    central system sign

    S

    i

    g

    n

    -

    S

    e

    r

    v

    er

    -

    A

    p

    p

    l

    c

    s

    -

    S

    e

    r

    v

    e

    r-

    A

    p

    p

    l

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    18/38

    OCIT-C_Protocol_V1_R1 Page 18 of 38

    2.5.7.1.1.2 Switching a sign (error case)The following image describes the sequence to issue put commands (error case):

    Soap-

    Client-I

    Soap-

    Server-Iput (Sign Switch

    Command)

    Soap::put-

    Result

    Soap-

    Client-I

    Soap-

    Server-I

    Soap-

    Client-I

    Soap-

    Server-I

    Soap-

    Server-I

    Soap-

    Server-I

    put (Sign Switch State-n.o.k.)

    Soap::put-

    Result

    forward switch to

    application

    change state

    to n.o.k( not

    accepted

    switch

    command)

    switch command to the

    interface

    change state

    n.o.k.

    central system sign

    S

    i

    gn

    -

    S

    e

    r

    v

    e

    r

    -

    A

    p

    p

    l

    c

    s-

    S

    e

    r

    v

    e

    r

    -

    A

    p

    p

    l

    put (Sign Switch

    Command)

    Soap::put-

    Result

    forward switch to

    application

    switch command to the

    interface again (repeat after

    delay max. 3 times)

    Sequence continues

    depending on the

    following answeres

    of the sign server.

    In case of a not received answer the switch commands are repeated after a (configurable) de-

    lay.

    The same applies for failures on the LAN (no response from SignServer) or not finally con-

    firmed sign switches, wherever the error occurs (no state transition to state busy or no state

    transition to state o.k.).

    The repeating will be stopped after three tries, which have been not successful. Then the sign

    state at the central system side changes to n.o.k.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    19/38

    OCIT-C_Protocol_V1_R1 Page 19 of 38

    2.5.7.1.1.3 Sign states/content transmission/Connection SupervisionThe following image describes the sequence to exchange state and contents information:

    Soap-

    Client-I

    Soap-

    Server-I

    Soap-

    Client-I

    Soap-

    Server-I

    Soap-

    Client-I

    Soap-

    Server-I

    Soap-

    Server-I

    Soap-

    Server-I

    put (Sign Switch State-n.o.k.)

    Soap::put-

    Result

    change state

    to n.o.k(any

    errer detcted

    on sign)

    change state

    n.o.k.

    central system sign

    S

    i

    g

    n

    -

    Se

    r

    v

    e

    r

    -

    A

    p

    p

    l

    c

    s

    -

    S

    er

    v

    e

    r

    -

    A

    p

    p

    l

    put (Sign Switch State-o.k.)Soap::put-

    Result

    change state

    to o.k(sign

    becomes o.k.)

    change state

    o.k.

    put (Sign Switch State-o.k.)

    Soap::put-

    Result

    change state

    to o.k(sign

    becomes o.k.)

    change state

    o.k.

    The signserver updates the

    central system periodicly.

    (Lifecycle telegramm). In

    case of non reachable

    serverTMS the sign falls

    back to default.

    The sign server updates the central system periodicly, although the state does not changed.

    Therefore central system gets notice

    - in case a sign connected to the signserver changes its state

    - in case a sign changes its contents (e.g. local control)

    - in case the sign server is unreachable (detected time out at the central system side)

    Therefore the Sign Server gets notice

    - in case central system is unreachable.

    Under this circumstance the SignServer switches all signs to default text.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    20/38

    OCIT-C_Protocol_V1_R1 Page 20 of 38

    22..55..77..22 BBiiddiirreeccttiioonnaallccoommmmuunniiccaattiioonnsseeqquueenncceessppoolllliinnggccuurrrreennttssttaattee

    2.5.7.2.1 Switching a sign (sequence)

    Soap-

    Client-I

    Soap-

    Server-I

    put (Sign Switch Command)

    Soap::put-

    Result

    Soap-

    Client-I

    Soap-

    Server-I

    forward switch to

    application

    switchcommand to

    the interface

    get (Sign Switch State)

    get-response

    change state to o.k.(successful

    switch command)

    change state to o.k.

    central system sign

    S

    i

    g

    n

    -

    S

    e

    r

    v

    e

    r

    -

    A

    p

    p

    l

    c

    s

    -

    S

    e

    r

    v

    e

    r

    -

    A

    p

    p

    l

    get (Sign Switch State)

    get-response

    get (Sign Switch State)

    get-response

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    21/38

    OCIT-C_Protocol_V1_R1 Page 21 of 38

    Soap-

    Client-I

    Soap-

    Server-I

    put (Sign Switch Command)

    Soap::put-

    Result

    Soap-Client-I Soap-Server-I

    forward switch to

    application

    switchcommand to

    the interface

    get (Sign Switch State)

    get-response

    change state to o.k.(successful

    switch command)

    change state to o.k.

    central system sign

    S

    i

    g

    n

    -

    S

    e

    r

    v

    er

    -

    A

    p

    p

    l

    c

    s

    -

    S

    e

    r

    v

    e

    r-

    A

    p

    p

    l

    get (Sign Switch State)

    get-response

    get (Sign Switch State)

    get-response

    22..66 OOSSIILLaayyeerriinngg

    The server is divided into different parts. First we have the Soap functionality which is covered

    by the Soap component. In addition to the Soap a protocol manager is used, whose task it is to

    implement all commands including the required data buffer for server functionality. Finally a

    data access layer is required to link from XML to the used database (e.g. Object Manager).

    The following image describes this in a layer modelling.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    22/38

    OCIT-C_Protocol_V1_R1 Page 22 of 38

    Soap-Client WebServer

    (Soap)

    PM-Client

    Protokoll-

    Manager

    Data/

    Application

    httphttp

    Data/

    Application

    Figure 5: Layers

    The client covers similar layers.

    22..77 PPrroottooccoollFFuunnccttiioonnssiinnDDeettaaiill

    Available protocol functions

    getContentInfo

    get

    inquireAll,

    put

    delete.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    23/38

    OCIT-C_Protocol_V1_R1 Page 23 of 38

    element Protokoll

    Figure 6: Available Commands

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    24/38

    OCIT-C_Protocol_V1_R1 Page 24 of 38

    22..77..11 ggeettCCoonntteennttIInnffoo

    getContentInfo has no parameters, besides name of the client and the password and optionalthe watchdog.

    As response you receive a list of all available object types including access rights and recom-

    mended update cycle to them.

    22..77..22 ggeett

    get has besides the standard parameters either start and endtime to get all values within thistime range or it includes the position number from where the request is related to. Usualy the

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    25/38

    OCIT-C_Protocol_V1_R1 Page 25 of 38

    position number is the positionnumber returned by the latest inquireAllResponse or getRe-

    sponse.

    So the inquiry returns all values since last request. This is the recommended way how to usethis interface.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    26/38

    OCIT-C_Protocol_V1_R1 Page 26 of 38

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    27/38

    OCIT-C_Protocol_V1_R1 Page 27 of 38

    22..77..33 iinnqquuiirreeAAllll

    Inquire all includes only standard parameters.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    28/38

    OCIT-C_Protocol_V1_R1 Page 28 of 38

    As response all topical values will be returned.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    29/38

    OCIT-C_Protocol_V1_R1 Page 29 of 38

    22..77..44 ppuutt

    put includes all data instances which should be configured.

    As response you get unconfigurable data instances (usually none).

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    30/38

    OCIT-C_Protocol_V1_R1 Page 30 of 38

    22..77..55 ddeelleettee

    delete removes data ion case this is possible, Data instances to delete have to be added to thefilterList.

    As response you get the data instances, which could not be deleted.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    31/38

    OCIT-C_Protocol_V1_R1 Page 31 of 38

    22..77..66 PPaarraammeetteerrss

    There are standard parameters mentioned above and defined here:

    Inputparameter

    UserName and and UserPasswd authentifies the userUserName and and UserPasswd are transferred in plain text. Authentification

    should not be used for security purposes in consequence.

    Watchdog is a structure with which the client tells the server when the server canexpect the next call of the client.

    Watchdog time can be used for timeout supervision of the client at the server

    side.

    storeTime indicates the start of the requested (or responded) dataIt is only used for historical data access.

    end_store indicates the end of the requested (or responded) data. It is only used

    for historical data access.

    position indicates a pointer in the servers buffer.The position is responded in an inquireAll- or get-Response and used for the next

    get request to incicate the next read position in the servers data buffer (refer

    to chapter2.5.1 Data Buffering and position handling)

    filterlist List of objects, which are to be readWith the help of the filter list the amount of read data can be restricted (to those

    mentioned in the filter list)

    Outputparameter

    LastStart

    is the date/time stamp of the last server start. In case of a change of lastStart

    (from one server response to next server response) the client has to resynchronise

    by using the command inquireAll.

    Changed Last start has to be used as an indicator for resynchronisation

    of data.

    Errorcode is an error code, in case of an error executing a command. In case ofwrong XML-Structures errorcode will not be used, SOAP-Fault will be returned

    instead.

    Errortxt is a human readable description of the error code.

    position Position of last data accessed. Is to be used for following get access.

    Datalist returned data container

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    32/38

    OCIT-C_Protocol_V1_R1 Page 32 of 38

    33 DDaattaassttrruuccttuurreessData structures embedded in the protocol (e.g. the mentioned commands put, inquireAllRe-

    sponse ) are defined in own scheme definitions.

    They are not scope of this document (...).

    44 HHoowwttoouussee

    This chapter describes how to use server and client depending on different use cases. This can

    be only a recommendation. The real architecture has to be decided on each certain case.

    44..11 DDaattaaddeelliivveerryyiinntteerrffaaccee//oonneeoorrmmoorreeCCoonnssuummeerr

    In case there are several consumers requiring data from time to time and not under real time

    requirements the following architecture is recommended.

    The data source includes the SoapServerInterface, which implements functional-ity like data buffering.

    The data consumers include the SoapClientInterface, which implement the accessto the soap server in case the data is required (commands inquire and get).

    This includes the following advantages:

    - reduces costs because the client can access the server on demand

    - improves the acceptance of the protocol because the SoapClientInterface is easier

    to implement

    - there is no need that the data source knows anything about the consumers.

    - only one communication interface at the data source

    In any case of internet providing the data source has to be server and the internet service is

    client.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    33/38

    OCIT-C_Protocol_V1_R1 Page 33 of 38

    Data Sink

    Data Source Data Sink

    SoapServer-

    Interface

    Data

    SoapClient-

    Interface

    further use of

    data

    44..22 CCoonnffiigguurraattiioonnIInntteerrffaaccee

    In case a system (data source) requires a configuration interface at the data sink, the following

    architecture is recommended:

    The data source is client

    The data sink is server

    This includes the following advantages:

    - transmission on demand

    - realtime configuration (no polling required)

    - more than one configuration interface at one Data Sink with the same

    communication interface

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    34/38

    OCIT-C_Protocol_V1_R1 Page 34 of 38

    Data Source

    SoapClient-

    Interface

    Data

    Data Sink

    SoapServer-

    Interface

    further use of

    data

    Data Source

    SoapClient-

    Interface

    Data

    This interface is used in the following applications:

    - in case a subsystem likes to get rid of measured data like roadwork man-agement systems or subsystems with a kind of data forwarding interface,

    then it uses the client as a simple way to forward data to the data sink.

    It should only be used for a view object types to avoid overload situa-

    tions.

    44..33 IInntteerrffaacceebbeettwweeeennCCeennttrraallUUnniittssttoouuppddaatteeiittssddaattaa((uunniiddiirreeccttiioonnaall))

    In case of data exchange between Central units the following interface is recommended.

    - Data source is Server

    - Data sink is client

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    35/38

    OCIT-C_Protocol_V1_R1 Page 35 of 38

    CentralUnit as Data

    Source

    Central Unit(s) as

    Consumer

    SoapServer-

    Interface

    Data

    SoapClient-

    Interface

    further use of

    data

    In fact we have the same configuration as mentioned within chapterData delivery interface /

    one or more Consumer.

    44..44 IInntteerrffaacceebbeettwweeeennCCeennttrraallUUnniittssttoouuppddaatteeiittssddaattaa((bbiiddiirreeccttiioonnaall))

    In case an interface in two directions is required it is clear to implement the interface twice,because the Central unit is server and client at the same time.

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    36/38

    OCIT-C_Protocol_V1_R1 Page 36 of 38

    CentralUnit 1 CentralUnit2

    SoapServer

    -Interface

    Data

    Soap-

    Client-

    Interface

    SoapServer

    -Interface

    Soap-

    Client-

    Interface

    Data

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    37/38

    OCIT-C_Protocol_V1_R1 Page 37 of 38

  • 8/12/2019 2. Ocit-c Protocol v1 r1

    38/38

    OCIT-C_Protocol_V1_R1

    Copyright 2010 ODG & Partner