prepareReporting static method

int prepareReporting({ DataSource? dataSource, int categId = 0, })

Prepares a report using the device's current high-accuracy position.

Validates position accuracy and rate limits, then generates a preparation ID for submitting a report via report. Required for most report categories. The position must be classified as high-accuracy by the map-matching system to ensure report reliability.

Operates in two modes based on categId:

• Preparing mode (categId = 0): Returns a preparation ID for use with report. The ID expires after a short time (typically minutes).
• Dry run mode (categId ≠ 0): Tests if reporting is possible for the category without actually preparing. Returns error code as integer (check against GemError ID values).

Prerequisites

• High-accuracy position data available from PositionService or specified dataSource. Low-accuracy positions are rejected.
• dataSource must have type DataSourceType.live.

Parameters

• dataSource: Optional DataSource providing position. If null, uses current PositionService data source. Must be live type with high-accuracy position data.
• categId: Category ID for dry run validation, or 0 for actual preparation (default: 0). Use 0 when preparing for report submission.

Returns

Dry run mode (categId ≠ 0):

• GemError.suspended.id if report rate limit exceeded.
• GemError.invalidInput.id if categId is not a valid category ID.
• GemError.notFound.id if no valid high-accuracy position available.
• GemError.required.id if dataSource type is not DataSourceType.live.

Preparing mode (categId = 0):

• GemError.suspended.id if report rate limit exceeded.
• GemError.notFound.id if no valid high-accuracy position available.
• Positive integer: Preparation ID for use with report (valid for short duration).

See also:

• prepareReportingCoords - Prepares report for explicit coordinates (Weather Hazard only).
• report - Submits prepared report using returned preparation ID.
• PositionService - Provides position data for reporting.

Implementation

static int prepareReporting({DataSource? dataSource, final int categId = 0}) {
  dataSource ??= PositionService.getDataSource();
  final OperationResult result = staticMethod(
    'SocialOverlay',
    'prepareReporting',
    args: <String, dynamic>{
      'categId': categId,
      'dataSource': dataSource == null ? 0 : dataSource.pointerId,
    },
  );
  return result['result'];
}