콘텐츠로 이동
무료 평가 시작

pdcomm::SecsItem

클래스

소유되는 불변(immutable) SECS-II 데이터 아이템입니다(SEMI E5 9절).

class SecsItem

선언 위치: #include <pdcomm.hpp>

SecsItem은 자식 아이템의 리스트이거나, SECS-II 형식(PDCOMM_SECS_ASCII, PDCOMM_SECS_BINARY, PDCOMM_SECS_U4 등) 중 하나로 된 기본(primitive) 값입니다. 기본 값의 페이로드는 회선상의 원시 바이트입니다. 숫자 값은 빅 엔디언(big-endian)이며, ASCII 바이트는 0부터 127까지여야 합니다. 각 아이템은 생성할 때 받은 PdcommSecsLimits를 저장하고, 자식과 인코딩에 다시 사용합니다.

아이템은 뷰가 아니라 값입니다. 모든 팩터리 함수와 getter는 독립된 사본을 반환하므로, 부모를 해제해도 자식은 무효화되지 않으며, GEM 결과가 반환한 아이템은 결과와 끝점이 사라진 뒤에도 유효합니다.

const std::vector<uint8_t> temperature = {0x41, 0xac, 0, 0};  // F4 21.5
auto value = pdcomm::SecsItem::primitive(PDCOMM_SECS_F4, temperature, limits);
auto lot = pdcomm::SecsItem::primitive(
    PDCOMM_SECS_ASCII, std::vector<uint8_t>{'L', 'O', 'T', '-', '0', '0', '1'}, limits);
auto pair = pdcomm::SecsItem::list({&value, &lot}, limits);
std::vector<uint8_t> wire = pair.bytes();  // encoded L[2] F4 A

참고

  • PdcommSecsItem을 감싸는 이동 전용(move-only) RAII 래퍼입니다. 기본 생성되었거나 이동된(moved-from) 아이템은 비어 있으며, operator bool로 확인합니다. 읽기 전용 호출(info(), child(), bytes(), payload())은 하나의 아이템에서 동시에 실행할 수 있지만, 소멸은 이 호출들과 경합하면 안 됩니다.

멤버

SecsItem

생성자

네이티브 핸들을 소유하지 않는 빈 아이템을 만듭니다.

SecsItem() noexcept = default

선언 위치: #include <pdcomm.hpp>

빈 아이템은 "값 없음"을 나타낼 때 사용합니다. 예를 들어 GEM 결과에 본문이 없을 때입니다.

SecsItem

생성자

other가 소유한 네이티브 핸들의 소유권을 가져옵니다.

SecsItem(SecsItem &&other) noexcept

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
other원본 래퍼입니다. 이 래퍼는 비게 됩니다.

SecsItem

생성자

복사할 수 없습니다. 래퍼가 네이티브 핸들을 단독으로 소유합니다.

SecsItem(const SecsItem &) = delete

선언 위치: #include <pdcomm.hpp>

adopt

메서드

네이티브 아이템 핸들을 감싸고 그 소유권을 가져옵니다.

static SecsItem adopt(PdcommSecsItem *handle) noexcept

선언 위치: #include <pdcomm.hpp>

pdcomm_secs_decode() 같은 C 함수가 반환한 핸들을 관리할 때 사용합니다.

매개변수

이름설명
handle소유할 유효한 핸들이며, 빈 아이템이면 nullptr입니다. 이후에는 다른 어떤 것도 이 핸들을 소유하거나 소멸하면 안 됩니다.

반환값

범위를 벗어날 때 handle을 소멸하는 래퍼입니다.

bytes

메서드

아이템을 SECS-II 회선 형식으로 인코딩합니다.

std::vector<uint8_t> bytes() const

선언 위치: #include <pdcomm.hpp>

아이템 헤더는 최소한의 길이 바이트 수를 사용합니다. 기본 아이템의 페이로드 바이트는 그대로 유지합니다.

반환값

완전히 인코딩된 아이템입니다.

참고

  • 예외 pdcomm::Error: 아이템이 비어 있으면 PDCOMM_INVALID_ARGUMENT입니다.

child

메서드

리스트 아이템의 자식 하나의 사본을 반환합니다.

SecsItem child(size_t index) const

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
index0부터 시작하는 자식 위치입니다.

반환값

자식의 독립된 사본입니다. 이 리스트를 해제해도 영향을 받지 않습니다.

참고

  • 예외 pdcomm::Error: 아이템이 비어 있거나 리스트가 아니면 PDCOMM_INVALID_ARGUMENT, index가 자식 수보다 작지 않으면 PDCOMM_OUT_OF_RANGE입니다.

decode

메서드

벡터에서 인코딩된 SECS-II 아이템 정확히 하나를 디코딩합니다.

static SecsItem decode(const std::vector<uint8_t> &data, const PdcommSecsLimits &limits, size_t *errorOffset = nullptr)

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
data인코딩된 아이템 바이트입니다.
limits디코딩한 트리가 만족해야 하는 한도입니다. 아이템에 저장됩니다.
errorOffset실패한 필드의 오프셋을 받는 선택 사항인 출력입니다.

반환값

디코딩한 아이템입니다.

참고

  • 예외 pdcomm::Error: 포인터와 길이를 받는 decode() 오버로드와 같은 상태입니다.

decode

메서드

인코딩된 SECS-II 아이템 정확히 하나를 디코딩합니다.

static SecsItem decode(const uint8_t *data, size_t length, const PdcommSecsLimits &limits, size_t *errorOffset = nullptr)

선언 위치: #include <pdcomm.hpp>

입력에는 뒤따르는 바이트 없이 완전한 아이템 하나만 있어야 합니다. 디코딩한 값은 복사되므로, 호출 뒤에 data를 해제해도 됩니다.

매개변수

이름설명
data인코딩된 아이템 바이트입니다.
lengthdata에 있는 바이트 수입니다.
limits디코딩한 트리가 만족해야 하는 한도입니다. 아이템에 저장됩니다.
errorOffset선택 사항인 출력입니다. 디코딩에 실패하면 처음 누락된 바이트가 아니라 실패한 필드의 시작 오프셋을 받습니다.

반환값

디코딩한 아이템입니다.

참고

  • 예외 pdcomm::Error: 입력이 일찍 끝나면(길이 0인 nullptr 포함) PDCOMM_TRUNCATED, 헤더나 폭이 잘못되었거나 ASCII가 아닌 텍스트 또는 뒤따르는 데이터가 있으면 PDCOMM_INVALID_DATA, limits를 넘으면 PDCOMM_LIMIT_EXCEEDED, 포인터가 잘못되었거나 limits.struct_size가 너무 작으면 PDCOMM_INVALID_ARGUMENT입니다.

info

메서드

아이템의 형식과 크기를 설명합니다.

PdcommSecsInfo info() const

선언 위치: #include <pdcomm.hpp>

반환값

format(PDCOMM_SECS_* 코드), count(리스트이면 자식 수, 기본 아이템이면 요소 수), encoded_length, node_count, depth를 담은 PdcommSecsInfo입니다.

참고

  • 예외 pdcomm::Error: 아이템이 비어 있으면 PDCOMM_INVALID_ARGUMENT입니다.

list

메서드

children의 사본을 담는 리스트 아이템을 만듭니다.

static SecsItem list(const std::vector<const SecsItem *> &children, const PdcommSecsLimits &limits)

선언 위치: #include <pdcomm.hpp>

전체 크기, 아이템 개수, 깊이를 limits와 비교해 확인한 뒤 자식을 복사합니다. 원래 아이템의 소유권은 호출자에게 남습니다.

매개변수

이름설명
children순서대로 복사할 아이템입니다. 빈 벡터는 빈 리스트를 만듭니다. 모든 포인터는 비어 있지 않은 아이템을 가리켜야 합니다.
limits새 트리 전체의 한도입니다. 아이템에 저장됩니다.

반환값

새 리스트 아이템입니다.

참고

  • 예외 pdcomm::Error: 자식이 nullptr이거나 비어 있으면 PDCOMM_INVALID_ARGUMENT, 트리가 limits를 넘으면 PDCOMM_LIMIT_EXCEEDED입니다.

list

메서드

children의 사본을 담는 리스트 아이템을 만듭니다.

static SecsItem list(std::initializer_list<const SecsItem *> children, const PdcommSecsLimits &limits)

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
children순서대로 복사할 아이템입니다. 모든 포인터는 비어 있지 않은 아이템을 가리켜야 합니다.
limits새 트리 전체의 한도입니다. 아이템에 저장됩니다.

반환값

새 리스트 아이템입니다.

참고

  • 예외 pdcomm::Error: 벡터를 받는 list() 오버로드와 같은 상태입니다.

nativeHandle

메서드

C API를 직접 호출할 때 쓰도록 소유한 네이티브 핸들을 반환합니다.

PdcommSecsItem *nativeHandle() noexcept

선언 위치: #include <pdcomm.hpp>

반환값

핸들이며, 빈 아이템이면 nullptr입니다. 소유권은 이 래퍼에 남습니다.

nativeHandle

메서드

읽기 전용 C API 호출에 쓰도록 소유한 네이티브 핸들을 반환합니다.

const PdcommSecsItem *nativeHandle() const noexcept

선언 위치: #include <pdcomm.hpp>

반환값

핸들이며, 빈 아이템이면 nullptr입니다. 소유권은 이 래퍼에 남습니다.

operator bool

메서드

래퍼가 네이티브 아이템을 소유하는지 알려 줍니다.

explicit operator bool() const noexcept

선언 위치: #include <pdcomm.hpp>

반환값

아이템을 소유하면 true입니다. 비어 있거나 이동된(moved-from) 아이템이면 false입니다.

operator=

메서드

현재 핸들을 해제한 뒤 other가 소유한 핸들의 소유권을 가져옵니다.

SecsItem &operator=(SecsItem &&other) noexcept

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
other원본 래퍼입니다. 이 래퍼는 비게 됩니다.

반환값

이 래퍼입니다.

operator=

메서드

복사 대입할 수 없습니다. 래퍼가 네이티브 핸들을 단독으로 소유합니다.

SecsItem &operator=(const SecsItem &) = delete

선언 위치: #include <pdcomm.hpp>

payload

메서드

기본 아이템의 원시 페이로드 바이트를 복사합니다.

std::vector<uint8_t> payload() const

선언 위치: #include <pdcomm.hpp>

반환값

회선 순서의 페이로드입니다. 빈 기본 값이면 비어 있습니다.

참고

  • 예외 pdcomm::Error: 아이템이 비어 있거나 리스트이면 PDCOMM_INVALID_ARGUMENT입니다. 리스트에는 기본 페이로드가 없기 때문입니다.

primitive

메서드

페이로드 벡터로 기본 아이템을 만듭니다.

static SecsItem primitive(uint8_t format, const std::vector<uint8_t> &data, const PdcommSecsLimits &limits)

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
formatSECS-II 형식 코드입니다. PDCOMM_SECS_LIST는 거부됩니다.
data회선 순서의 페이로드입니다(숫자는 빅 엔디언). 비어 있어도 됩니다.
limits아이템의 한도입니다. 아이템에 저장됩니다.

반환값

새 아이템입니다.

참고

  • 예외 pdcomm::Error: 포인터와 길이를 받는 primitive() 오버로드와 같은 상태입니다.

primitive

메서드

원시 페이로드 바이트로 기본(primitive) 아이템을 만듭니다.

static SecsItem primitive(uint8_t format, const uint8_t *data, size_t length, const PdcommSecsLimits &limits)

선언 위치: #include <pdcomm.hpp>

매개변수

이름설명
formatPDCOMM_SECS_U4, PDCOMM_SECS_ASCII 같은 SECS-II 형식 코드(format code)입니다. PDCOMM_SECS_LIST는 거부되므로 대신 list()를 사용합니다.
data회선 순서의 페이로드입니다(숫자는 빅 엔디언). length가 0이면 nullptr일 수 있으며, 이 경우 빈 값을 만듭니다.
length페이로드 크기(바이트)입니다. 형식의 요소 폭의 배수여야 합니다.
limits아이템의 한도입니다. 아이템에 저장됩니다.

반환값

새 아이템입니다.

참고

  • 예외 pdcomm::Error: 알 수 없는 형식이거나 리스트 형식이면 PDCOMM_INVALID_ARGUMENT, 길이가 요소 폭의 배수가 아니거나 ASCII 바이트가 127보다 크면 PDCOMM_INVALID_DATA, limits를 넘으면 PDCOMM_LIMIT_EXCEEDED입니다.

~SecsItem

메서드

pdcomm_secs_destroy()로 네이티브 핸들을 해제합니다.

~SecsItem()

선언 위치: #include <pdcomm.hpp>

빈 아이템은 아무것도 해제하지 않습니다.

개인정보 처리방침