org.openmuc.openiec61850

## Class ClientSap

- java.lang.Object
- - org.openmuc.openiec61850.ClientSap

    public final class ClientSap
    extends java.lang.Object

The `ClientSap` class represents the IEC 61850 service access point for client applications. A client application that wants to connect to a server should first create an instance of `ClientSap`. Next all the necessary configuration parameters can be set. Finally the `associate` function is called to connect to the server. An instance of `ClientSap` can be used to create an unlimited number of associations. Changing the parameters of a ClientSap has no affect on associations that have already been created.

### Constructor Summary

Constructors
Constructor and Description
`ClientSap()` Use this constructor to create a default client SAP.
`ClientSap(javax.net.SocketFactory socketFactory)` Use this constructor to create a client SAP that uses the given `SocketFactory` to connect to servers.

### Method Summary

All Methods Instance Methods Concrete Methods
`ClientAssociation` `associate(java.net.InetAddress address, int port, java.lang.String authenticationParameter, ClientEventListener reportListener)` Connects to the IEC 61850 MMS server at the given address and port and returns the resulting association object.
`ClientAssociation` `associate(java.net.InetAddress address, int port, java.lang.String authenticationParameter, java.net.InetAddress localAddr, int localPort, ClientEventListener reportListener)` Connects to the IEC 61850 MMS server at the given address and port and returns the resulting association object.
`int` `getMaxMmsPduSize()` Gets the maximum MMS PDU size.
`byte[]` `getServicesSupportedCalling()` Gets the ServicesSupportedCalling parameter.
`void` `setAeQualifierCalled(int qualifier)` Sets the remote/called Application Entity Qualifier.
`void` `setAeQualifierCalling(int qualifier)` Sets the local/calling Application Entity Qualifier.
`void` `setApTitleCalled(int[] title)` Sets the remote/called Application Process Title.
`void` `setApTitleCalling(int[] title)` Sets the local/calling Application Process Title.
`void` `setMaxMmsPduSize(int size)` Sets the maximum MMS PDU size in bytes that the client association will support.
`void` `setMaxTPduSizeParameter(int maxTPduSizeParam)` Set the maxTPDUSize.
`void` `setMessageFragmentTimeout(int timeout)` Sets the message fragment timeout.
`void` `setPSelLocal(byte[] pSelLocal)` Sets the local/calling Presentation-Selector (P-SEL).
`void` `setPSelRemote(byte[] pSelRemote)` Sets the remote/called Presentation-Selector (P-SEL).
`void` `setResponseTimeout(int timeout)` Sets the default response timeout of the `ClientAssociation` that is created using this ClientSap.
`void` `setServicesSupportedCalling(byte[] services)` Sets the SevicesSupportedCalling parameter.
`void` `setSSelLocal(byte[] sSelLocal)` Sets the local/calling Session-Selector (S-SEL).
`void` `setSSelRemote(byte[] sSelRemote)` Sets the remote/called Session-Selector (S-SEL).
`void` `setTSelLocal(byte[] tSelLocal)` Sets the local/calling Transport-Selector (T-SEL).
`void` `setTSelRemote(byte[] tSelRemote)` Sets the remote/called Transport-Selector (T-SEL).

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### ClientSap

    public ClientSap()

Use this constructor to create a default client SAP.

#### ClientSap

    public ClientSap(javax.net.SocketFactory socketFactory)

Use this constructor to create a client SAP that uses the given `SocketFactory` to connect to servers. You could pass an SSLSocketFactory to enable SSL.

Parameters:
  `socketFactory` - the socket factory to construct the socket

### Method Detail

#### setMaxMmsPduSize

    public void setMaxMmsPduSize(int size)

Sets the maximum MMS PDU size in bytes that the client association will support. The client proposes this value to the server during association. If the server requires the use of a smaller maximum MMS PDU size, then the smaller size will be accepted by the client. The default size is 65000.

Parameters:
  `size` - cannot be less than 64. The upper limit is 65000 so that segmentation at the lower transport layer is avoided. The Transport Layer's maximum PDU size is 65531.

#### getMaxMmsPduSize

    public int getMaxMmsPduSize()

Gets the maximum MMS PDU size.

Returns:
  the maximum MMS PDU size.

#### setServicesSupportedCalling

    public void setServicesSupportedCalling(byte[] services)

Sets the SevicesSupportedCalling parameter. The given parameter is sent to the server but has no affect on the functionality of this client.

Parameters:
  `services` - the ServicesSupportedCalling parameter

#### getServicesSupportedCalling

    public byte[] getServicesSupportedCalling()

Gets the ServicesSupportedCalling parameter.

Returns:
  the ServicesSupportedCalling parameter.

#### setSSelRemote

    public void setSSelRemote(byte[] sSelRemote)

Sets the remote/called Session-Selector (S-SEL). The default remote S-SEL is byte[] { 0, 1 }.

Parameters:
  `sSelRemote` - the remote/called S-SEL.

#### setSSelLocal

    public void setSSelLocal(byte[] sSelLocal)

Sets the local/calling Session-Selector (S-SEL). The default local S-SEL is byte[] { 0, 1 }.

Parameters:
  `sSelLocal` - the local/calling S-SEL.

#### setPSelRemote

    public void setPSelRemote(byte[] pSelRemote)

Sets the remote/called Presentation-Selector (P-SEL). The default remote P-SEL is byte[] { 0, 0, 0, 1 }.

Parameters:
  `pSelRemote` - the remote/called P-SEL.

#### setPSelLocal

    public void setPSelLocal(byte[] pSelLocal)

Sets the local/calling Presentation-Selector (P-SEL). The default local P-SEL is byte[] { 0, 0, 0, 1 }.

Parameters:
  `pSelLocal` - the local/calling P-SEL.

#### setTSelRemote

    public void setTSelRemote(byte[] tSelRemote)

Sets the remote/called Transport-Selector (T-SEL). It is optionally transmitted in the OSI Transport Layer connection request (CR). The default remote T-SEL is byte[] { 0, 1 }.

Parameters:
  `tSelRemote` - the remote/called T-SEL. If null the T-SEL will be omitted. No maximum size is defined by the standard.

#### setTSelLocal

    public void setTSelLocal(byte[] tSelLocal)

Sets the local/calling Transport-Selector (T-SEL). It is optionally transmitted in the OSI Transport Layer connection request (CR). The default local T-SEL byte[] { 0, 0 }.

Parameters:
  `tSelLocal` - the local/calling T-SEL. If null the T-SEL will be omitted. No maximum size is defined by the standard.

#### setMaxTPduSizeParameter

    public void setMaxTPduSizeParameter(int maxTPduSizeParam)

Set the maxTPDUSize. The default maxTPduSize is 65531 (see RFC 1006).

Parameters:
  `maxTPduSizeParam` - The maximum length is equal to 2^(maxTPduSizeParam) octets. Note that the actual TSDU size that can be transfered is equal to TPduSize-3. Default is 65531 octets (see RFC 1006), 7 <= maxTPduSizeParam <= 16, needs to be set before listening or connecting

#### setApTitleCalled

    public void setApTitleCalled(int[] title)

Sets the remote/called Application Process Title. The default value is int[] { 1, 1, 999, 1, 1 }

Parameters:
  `title` - the remote/called AP title.

#### setApTitleCalling

    public void setApTitleCalling(int[] title)

Sets the local/calling Application Process Title. The default value is int[] { 1, 1, 999, 1 }

Parameters:
  `title` - the local/calling AP title.

#### setAeQualifierCalled

    public void setAeQualifierCalled(int qualifier)

Sets the remote/called Application Entity Qualifier. The default value is 12.

Parameters:
  `qualifier` - the remote/called AE Qualifier

#### setAeQualifierCalling

    public void setAeQualifierCalling(int qualifier)

Sets the local/calling Application Entity Qualifier. The default value is 12.

Parameters:
  `qualifier` - the local/calling AE Qualifier

#### setResponseTimeout

    public void setResponseTimeout(int timeout)

Sets the default response timeout of the `ClientAssociation` that is created using this ClientSap.

Parameters:
  `timeout` - the response timeout in milliseconds. The default is 20000.

#### setMessageFragmentTimeout

    public void setMessageFragmentTimeout(int timeout)

Sets the message fragment timeout. This is the timeout that the socket timeout is set to after the first byte of a message has been received. A request function (e.g. setDataValues()) will throw an IOException if the socket throws this timeout because the association/connection cannot recover from this kind of error.

Parameters:
  `timeout` - the timeout in milliseconds. The default is 10000.

#### associate

    public ClientAssociation associate(java.net.InetAddress address,
                                       int port,
                                       java.lang.String authenticationParameter,
                                       ClientEventListener reportListener)
                                throws java.io.IOException

Connects to the IEC 61850 MMS server at the given address and port and returns the resulting association object.

Parameters:
  `address` - the address to connect to.
  `port` - the port to connect to. Usually the MMS port is 102.
  `authenticationParameter` - an optional authentication parameters that is transmitted. It will be omitted if equal to null.
  `reportListener` - the listener to be notified of incoming reports
Returns:
  the association object
Throws:
  `java.io.IOException` - if any kind of error occurs trying build up the association

#### associate

    public ClientAssociation associate(java.net.InetAddress address,
                                       int port,
                                       java.lang.String authenticationParameter,
                                       java.net.InetAddress localAddr,
                                       int localPort,
                                       ClientEventListener reportListener)
                                throws java.io.IOException

Connects to the IEC 61850 MMS server at the given address and port and returns the resulting association object.

Parameters:
  `address` - the address to connect to
  `port` - the port to connect to. Usually the MMS port is 102.
  `authenticationParameter` - an optional authentication parameters that is transmitted. It will be omitted if equal to null.
  `localAddr` - the local address to use
  `localPort` - the local port to use
  `reportListener` - the listener to be notified of incoming reports
Returns:
  the association object.
Throws:
  `java.io.IOException` - if any kind of error occurs trying build up the association