이 페이지에서는 libsdv_telemetry_rust_wrapper 라이브러리의 유형, 메서드, 오류 처리를 설명합니다.
TelemetryServiceHolder 인터페이스
클라이언트의 기본 인터페이스는 TelemetryServiceHolder 구조체입니다. 이 인터페이스는 서비스 연결, 측정항목 구성, 데이터 보고서를 관리하는 전체 메서드 집합을 제공합니다.
서비스 수명 주기 관리
이러한 메서드는 기본 원격 분석 서비스와의 연결을 설정하고 종료합니다.
get
pub fn get() -> TelemetryResult<TelemetryServiceHolder>
원격 분석 서비스에 대한 스레드 안전 핸들을 가져오는 정적 메서드입니다.
이는 원격 분석 바인더 서비스가 준비될 때까지 기다리는 차단 호출입니다.
원격 분석 서비스는 TelemetryServiceHolder의 단일 인스턴스만 지원합니다. 이 메서드를 두 번 이상 호출하면 정의되지 않거나 예기치 않은 동작이 발생합니다.
TelemetryServiceHolder는 Send 및 Sync 트레이트를 구현하므로 Arc 인스턴스로 래핑하는 등 스레드 간에 안전하게 공유할 수 있습니다. TelemetryServiceHolder의 메서드 대부분은 async이며 동시에 사용할 수 있습니다.
| 반환 | |
|---|---|
TelemetryResult<TelemetryServiceHolder>
|
서비스 핸들을 포함하는 결과 또는 서비스를 가져올 수 없는 경우 TelemetryError 인스턴스
|
init
pub async fn init(
&self,
misc_status_callback: impl Fn(TelemetryServiceStatus) + Send + Sync + 'static,
report_ready_callback: impl Fn(ReportInfo) + Send + Sync + 'static,
) -> TelemetryResult<()>
비동기 콜백을 등록하여 서비스를 초기화합니다. TelemetryServiceHolder를 획득한 후 다른 상호작용 전에 이 메서드를 한 번 호출합니다.
| 매개변수 | |
|---|---|
misc_status_callback
|
impl Fn(TelemetryServiceStatus) + Send + Sync +
'static: 원격 분석 서비스에서 상태 및 오류 업데이트를 수신하고 처리하는 클로저
|
report_ready_callback
|
impl Fn(ReportInfo) + Send + Sync + 'static: 새 측정항목 보고서를 가져올 준비가 되면 알림을 수신하고 처리하는 클로저입니다.
|
| 반환 | |
|---|---|
TelemetryResult<()>
|
성공 시 빈 결과, 실패 시 TelemetryError 인스턴스 |
완료
pub fn finish(&self) -> TelemetryResult<()>
서비스 연결을 단계적으로 종료하고, 등록된 리스너를 지우고, 연결된 리소스를 정리합니다. 앱이 종료될 때 이 메서드를 한 번 호출합니다.
| 반환 | |
|---|---|
TelemetryResult<()>
|
성공 시 빈 결과, 실패 시 TelemetryError 인스턴스 |
측정항목 구성 관리
이러한 비동기 메서드는 데이터 수집 구성의 정의와 상태를 관리합니다.
원격 분석 서비스는 다음 두 상태로 구성을 유지합니다.
- 비활성: 구성이 검증되고 디스크에 저장되지만 데이터 수집에 사용되지 않습니다.
- 활성: 구성이 데이터를 수집하고 구성요소 (예: 트리거, 게시자)가 활성 상태입니다.
서비스가 다시 시작되고 기기가 재부팅되는 동안 구성이 유지되도록 서비스는 기기의 디스크에 구성을 저장합니다. 서비스는 모든 구성을 상태 기반 디렉터리 두 개에 저장하고 부팅 시 이를 검증하고 필요한 경우 활성화합니다.
add_metrics_config
pub async fn add_metrics_config(&self, serialized_config: &[u8]) -> TelemetryResult<String>
서비스에 새 측정항목 구성을 추가합니다. 구성 정보는 직렬화된 바이트 배열로 제공되어야 합니다. 추가된 구성은 기본적으로 비활성 상태입니다.
| 매개변수 | |
|---|---|
serialized_config
|
&[u8]: protobuf 직렬화 구성 데이터가 포함된 바이트 슬라이스
|
| 반환 | |
|---|---|
TelemetryResult<String>
|
성공 시 새로 추가된 구성의 UUID를 포함하는 결과, 실패 시 TelemetryError 인스턴스
|
activate_metrics_config
pub async fn activate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>
이전에 추가되었거나 비활성화된 측정항목 구성을 활성화하여 데이터 수집 및 보고를 시작합니다.
| 매개변수 | |
|---|---|
config_uuid
|
&str: 활성화할 구성의 UUID |
| 반환 | |
|---|---|
TelemetryResult<String>
|
성공 시 활성화된 구성의 UUID를 포함하는 결과 또는 실패 시 TelemetryError 인스턴스
|
deactivate_metrics_config
pub async fn deactivate_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>
활성 측정항목 구성의 데이터 수집 및 보고를 중지합니다. 구성은 서비스에 남아 있으며 나중에 다시 활성화할 수 있습니다.
| 매개변수 | |
|---|---|
config_uuid
|
&str: 비활성화할 구성의 UUID |
| 반환 | |
|---|---|
TelemetryResult<String>
|
성공 시 비활성화된 구성의 UUID를 포함하는 결과, 실패 시 TelemetryError 인스턴스
|
remove_metrics_config
pub async fn remove_metrics_config(&self, config_uuid: &str) -> TelemetryResult<String>
측정항목 구성을 영구적으로 삭제합니다. 구성 활성 상태인 경우 서비스에서 먼저 비활성화합니다.
| 매개변수 | |
|---|---|
config_uuid
|
&str: 삭제할 구성의 UUID |
| 반환 | |
|---|---|
TelemetryResult<String>
|
성공 시 삭제된 구성의 UUID를 포함하는 결과, 실패 시 TelemetryError 인스턴스
|
remove_all_metrics_configs
pub async fn remove_all_metrics_configs(&self) -> TelemetryResult<String>
기존 측정항목 구성을 모두 삭제하여 활성 상태인 측정항목을 비활성화합니다.
| 반환 | |
|---|---|
TelemetryResult<String>
|
성공 시 상태 메시지 문자열을 포함하는 결과 또는 실패 시 TelemetryError 인스턴스
|
get_active_metrics_config_uuids
pub async fn get_active_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>
활성 상태의 모든 구성의 UUID 목록을 서비스에 쿼리합니다.
| 반환 | |
|---|---|
TelemetryResult<Vec<String>>
|
성공 시 활성 측정항목 구성의 UUID 문자열 벡터를 포함하는 결과 또는 실패 시 TelemetryError 인스턴스
|
get_inactive_metrics_config_uuids
pub async fn get_inactive_metrics_config_uuids(&self) -> TelemetryResult<Vec<String>>
비활성 상태의 모든 구성의 UUID 목록을 서비스에 쿼리합니다.
| 반환 | |
|---|---|
TelemetryResult<Vec<String>>
|
성공 시 비활성 측정항목 구성의 UUID 문자열 벡터를 포함하는 결과 또는 실패 시 TelemetryError 인스턴스
|
측정항목 보고서 처리 및 검색
이러한 메서드를 사용하면 사용 가능한 보고서를 쿼리하고 수집된 보고서 데이터를 검색할 수 있습니다.
get_metrics_report
pub async fn get_metrics_report(&self, report_uuid: &str) -> TelemetryResult<MetricsReport>
특정 보고서 UUID의 전체 측정항목 보고서 데이터를 가져옵니다. report_ready_callback를 사용하거나 get_ready_reports_info를 호출하여 알림에서 보고서 UUID를 가져올 수 있습니다.
| 매개변수 | |
|---|---|
report_uuid
|
&str: 가져올 특정 보고서의 UUID |
| 반환 | |
|---|---|
TelemetryResult<MetricsReport>
|
성공 시 역직렬화된 MetricsReport protobuf 객체 또는 실패 시 TelemetryError 인스턴스를 포함하는 결과
|
get_ready_reports_info
pub async fn get_ready_reports_info(&self) -> TelemetryResult<Vec<ReportInfo>>
완료되어 검색할 준비가 된 모든 보고서의 목록을 원격 분석 서비스에 쿼리합니다. 콜백 알림이 누락된 경우 (예: report_ready_callback가 늦게 등록된 경우) 보고서 상태를 확인하는 데 유용합니다.
| 반환 | |
|---|---|
TelemetryResult<Vec<ReportInfo>>
|
성공 시 ReportInfo 객체의 벡터를 포함하는 결과, 실패 시 TelemetryError 인스턴스
|
핵심 유형, 콜백, 오류 처리
libsdv_telemetry_rust_wrapper는 일련의 맞춤 유형을 사용하여 원격 분석 서비스와 상호작용하고, 비동기 콜백을 관리하고, 서비스 오류를 처리합니다.
API 응답 및 오류 유형
이러한 유형은 요청된 작업의 즉각적인 성공 또는 실패를 나타내기 위해 라이브러리 메서드에 의해 직접 반환됩니다.
TelemetryResult
대부분의 메서드는 서비스 수준 오류에 특화된 표준 Result 유형의 별칭인 TelemetryResult<T>를 반환합니다.
pub type TelemetryResult<T> = Result<T, TelemetryError>;
TelemetryError
TelemetryError 구조체는 모든 실패를 캡슐화하고 자세한 서비스별 오류 정보를 제공합니다.
| 필드 | |
|---|---|
status
|
TelemetryServiceStatusCodes: 열거 가능한 오류 코드
|
message
|
String: 오류를 자세히 설명하는 설명 메시지 |
TelemetryServiceStatusCodes
API 호출 및 내부 서비스 상태의 결과를 나타내는 숫자 열거형입니다. 이러한 코드는 TelemetryError 및 TelemetryServiceStatus에서 모두 사용됩니다. 예를 들면 다음과 같습니다.
| Codes | ||
|---|---|---|
200
|
TELEMETRY_SERVICE_API_CALL_SUCCESS
|
성공 |
402
|
METRICS_CONFIG_PARSE_ERROR
|
측정항목 구성을 파싱할 수 없음 |
407
|
REMOVE_METRICS_CONFIG_FAILED
|
측정항목 구성을 삭제할 수 없음 |
417
|
METRICS_CONFIG_RUNTIME_EXPRESSION_NODE_EVALUATION_ERROR
|
측정항목 구성에 지정된 표현식을 평가할 수 없음 |
비동기 콜백 유형
등록된 리스너 (misc_status_callback 및 report_ready_callback)는 이러한 유형을 클라이언트에 전달하여 백그라운드 프로세스에 관한 업데이트를 제공합니다.
TelemetryServiceStatus
TelemetryServiceStatus 구조체는 서비스 초기화 중에 등록되는 init의 misc_status_callback 클로저의 인수로 사용됩니다. 서비스의 상태 및 런타임 문제(예: 데이터 소스와의 연결 해제)에 관한 비동기 업데이트를 제공합니다.
| 필드 | |
|---|---|
id
|
usize: 상태 이벤트의 고유 식별자 |
code
|
TelemetryServiceStatusCodes: 이벤트를 분류하는 상태 코드
|
message
|
String: 사람이 읽을 수 있는 상태 설명 |
details
|
Option<StatusDetails>: 상태에 관한 추가 컨텍스트를 제공하는 구조화된 데이터(선택사항)
|
StatusDetails
이 enum은 특정 오류 컨텍스트를 래핑합니다. details이 TelemetryServiceStatus에 있는 경우 다음 변형 중 하나입니다.
| 변형 | |
|---|---|
AggregationPublisherErrorDetails
|
데이터를 집계하는 중에 오류가 발생했습니다. |
ServicePublisherErrorDetails
|
서비스에 연결하려고 시도하는 중에 오류가 발생했습니다. |
ConditionalTriggerErrorDetails
|
조건부 트리거의 표현식을 평가하는 중에 오류가 발생했습니다. |
MetricsReportGeneratorErrorDetails
|
측정항목 보고서를 생성하는 중에 오류가 발생했습니다. |
ServiceErrorDetails
|
서비스에서 새 메시지를 수신하는 중에 오류가 발생했습니다. |
FileIOErrorDetails
|
파일 I/O 오류가 발생했습니다. |
각 enum 변형에는 더 많은 컨텍스트를 제공하는 추가 필드가 포함되어 있습니다.
ReportInfo
ReportInfo 구조체는 서비스 초기화 중에 등록되는 init의 report_ready_callback 클로저의 인수로 사용됩니다.
여기에는 측정항목 보고서를 설명하는 식별자가 포함됩니다.
| 필드 | |
|---|---|
config_uuid
|
String: 보고서를 생성한 측정항목 구성의 UUID |
report_uuid
|
String: 검색할 준비가 된 측정항목 보고서의 UUID |
report_uuid 필드는 측정항목 보고서 자체를 추가로 가져오는 데만 필요하며 (get_metrics_report 참고) config_uuid은 소스에 관한 추가 정보로만 사용됩니다.