validateConnection method

Future<void> validateConnection(
  1. String host, {
  2. int port = 443,
  3. Duration? timeout,
})

Validates that host:port is allowed under this instance's pinning configuration. Returns normally on success.

The platform composes the leaf-certificate fetch and pin verification inside a single channel call, so the certificate never enters the Dart isolate. This is the recommended entry point for cert-pinned HTTPS; fetchCertificate and verify remain available for diagnostic or custom-flow use cases.

try {
  await TrustPin.shared.validateConnection('api.example.com');
} on TrustPinException catch (e) {
  if (e.isPinsMismatch) {
    // Certificate didn't match any configured pin.
  }
}

timeout is an optional upper bound on the entire operation (TLS handshake, chain validation, configuration refresh if any, and pin comparison). When null, the platform default is used.

  • Throws TrustPinException with code INVALID_PROJECT_CONFIG if setup has not been called.
  • Throws TrustPinException with code INVALID_SERVER_CERT on connection failure.
  • Throws TrustPinException with code DOMAIN_NOT_REGISTERED if domain is not configured (strict mode only).
  • Throws TrustPinException with code PINS_MISMATCH if the certificate is rejected.
  • Throws TrustPinException with code ALL_PINS_EXPIRED if no usable pins remain for the domain.
  • Throws TrustPinException with code ERROR_FETCHING_PINNING_INFO if pinning information cannot be retrieved.
  • Throws TrustPinException with code FETCH_CERTIFICATE_TIMEOUT if timeout is exceeded.

Implementation

Future<void> validateConnection(
  String host, {
  int port = 443,
  Duration? timeout,
}) async {
  try {
    await TrustPinSDKPlatform.instance.validateConnection(
      host,
      port: port,
      timeoutMs: timeout?.inMilliseconds,
      instanceId: _instanceId,
    );
  } catch (e) {
    throw TrustPinException.fromPlatformException(e);
  }
}