declareAdvancedPublisher method

AdvancedPublisher declareAdvancedPublisher(Object keyExpr, { AdvancedPublisherOptions? options, })

Declares an advanced publisher on the given keyExpr.

Returns an AdvancedPublisher with optional cache, publisher detection, and sample miss detection capabilities. Call AdvancedPublisher.close when done.

keyExpr is a String or a KeyExpr, including a declared one.

Throws UnsupportedError if the loaded native lacks the unstable API — that gate runs FIRST, before the key expression is even looked at. Throws ArgumentError if keyExpr is neither a String nor a KeyExpr, or if the cache bound is negative — checked before any native call. Throws ZenohException if the key expression is invalid. Throws StateError if the session has been closed.

Implementation

AdvancedPublisher declareAdvancedPublisher(
  Object keyExpr, {
  AdvancedPublisherOptions? options,
}) {
  requireUnstable();
  final opts = options ?? const AdvancedPublisherOptions();
  // CONV-4(a): the cache bound's domain is checked HERE, before the key
  // expression is loaned, so a negative bound costs no native call at all.
  final maxSamples = opts.cache?.maxSamples;
  if (maxSamples != null && maxSamples < 0) {
    throw ArgumentError.value(
      maxSamples,
      'maxSamples',
      "must be >= 0; null leaves canon's own default in place",
    );
  }
  // The extension does not re-implement the loan; the union seam owns it.
  return withLoanedKeyExpr(keyExpr, 'keyExpr', (loanedKe) {
    return AdvancedPublisher.declare(
      loanedHandle,
      loanedKe,
      keyExprString(keyExpr, 'keyExpr'),
      enableCache: opts.cache != null,
      cacheMaxSamples: maxSamples,
      publisherDetection: opts.publisherDetection,
      sampleMissDetection: opts.sampleMissDetection,
      heartbeatMode: opts.heartbeatMode,
      heartbeatPeriodMs: opts.heartbeatPeriodMs,
      enableMatchingListener: opts.enableMatchingListener,
    );
  });
}