ChildSessionCallback

Kotlin |Java

interface ChildSessionCallback

android.net.ipsec.ike.ChildSessionCallback

Callback interface for receiving state changes of a Child Session.

ChildSessionCallback MUST be unique to each Child Session. It is registered when callers are requesting a new Child Session. It is automatically unregistered when a Child Session or the parent IKE Session is closed.

ChildSessionCallbacks are also used for identifying Child Sessions. It is required when a caller wants to delete a specific Child Session.

Summary

Public methods
abstract Unit	`onClosed()` Called when the Child Session is closed.
open Unit	`onClosedWithException(exception: IkeException)` Called if the Child Session setup failed or Child Session is closed because of a fatal error.
abstract Unit	`onIpSecTransformCreated(ipSecTransform: IpSecTransform, direction: Int)` Called when an `IpSecTransform` is created by this Child Session.
abstract Unit	`onIpSecTransformDeleted(ipSecTransform: IpSecTransform, direction: Int)` Called when an `IpSecTransform` is deleted by this Child Session.
abstract Unit	`onOpened(sessionConfiguration: ChildSessionConfiguration)` Called when the Child Session setup succeeds.

Public methods

onClosed

Added in API level 31

abstract fun onClosed(): Unit

Called when the Child Session is closed.

This method will be called immediately after onIpSecTransformDeleted(android.net.IpSecTransform,int) for the deleted IPsec SA pair is fired.

When the closure is caused by a local, fatal error, onClosedWithException(android.net.ipsec.ike.exceptions.IkeException) will be fired instead of this method.

onClosedWithException

Added in API level 31

open fun onClosedWithException(exception: IkeException): Unit

Called if the Child Session setup failed or Child Session is closed because of a fatal error.

This method will be called immediately after onIpSecTransformDeleted(android.net.IpSecTransform,int) for the deleted IPsec SA pair is fired.

Parameters
`exception`	IkeException: the detailed error information. This value cannot be `null`.

onIpSecTransformCreated

Added in API level 31

abstract fun onIpSecTransformCreated(
    ipSecTransform: IpSecTransform, 
    direction: Int
): Unit

Called when an IpSecTransform is created by this Child Session.

This method is fired when a Child Session is created or rekeyed.

The IpSecTransform must be applied to relevant sockets or interfaces when this method is called; traffic may otherwise flow over the socket or interface unprotected.

As this method is fired on an executor, there is an inherent race condition during rekeys where traffic may be routed through the old transforms while the remote has switched to using the new set of transforms.

To avoid the initial startup race condition where the transforms have not yet been applied, the onOpened(android.net.ipsec.ike.ChildSessionConfiguration) callback should be used as the authoritative signal that the socket or tunnel is ready, as it is fired after both transforms have had a chance to be applied.

Parameters
`ipSecTransform`	IpSecTransform: the created `IpSecTransform`. This value cannot be `null`.
`direction`	Int: the direction of this `IpSecTransform`. Value is `android.net.IpSecManager#DIRECTION_IN`, or `android.net.IpSecManager#DIRECTION_OUT`

onIpSecTransformDeleted

Added in API level 31

abstract fun onIpSecTransformDeleted(
    ipSecTransform: IpSecTransform, 
    direction: Int
): Unit

Called when an IpSecTransform is deleted by this Child Session.

This method is fired when a Child Session is closed or a Child Session has deleted old IPsec SA during rekey. When this method is fired due to Child Session closure, it will be followed by onClosed() or onClosedWithException(android.net.ipsec.ike.exceptions.IkeException).

Users SHOULD remove the IpSecTransform from the socket or interface when this method is called. Otherwise the IPsec traffic protected by this IpSecTransform will be discarded.

Parameters
`ipSecTransform`	IpSecTransform: the deleted `IpSecTransform`. This value cannot be `null`.
`direction`	Int: the direction of this `IpSecTransform`. Value is `android.net.IpSecManager#DIRECTION_IN`, or `android.net.IpSecManager#DIRECTION_OUT`

onOpened

Added in API level 31

abstract fun onOpened(sessionConfiguration: ChildSessionConfiguration): Unit

Called when the Child Session setup succeeds.

This method will be called immediately after onIpSecTransformCreated(android.net.IpSecTransform,int) for the created IPsec SA pair is fired.

Parameters
`sessionConfiguration`	ChildSessionConfiguration: the `ChildSessionConfiguration` of Child Session negotiated during Child creation. This value cannot be `null`.