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

PDComm.SecsItem

클래스

네이티브 메모리에 보관되는 변경할 수 없는 SECS-II(SEMI E5) 데이터 아이템입니다. 리스트이거나 형식이 지정된 기본 값 배열입니다.

public sealed class SecsItem : IDisposable

아이템은 From* 팩터리, SecsItem.Primitive, SecsItem.CreateList 또는 SecsItem.Decode로 만듭니다. 모든 팩터리는 메모리를 확보하기 전에 아이템을 SecsLimits와 비교해 검사합니다.

각 SecsItem은 자체 네이티브 메모리를 소유하므로 사용이 끝나면 해제합니다. 해제하지 않으면 종료자(finalizer)가 해제합니다. SecsItem.GetChild, GEM 결과, 그 밖의 PDComm API가 반환하는 아이템은 호출자가 소유하는 독립된 새 복사본입니다. 부모를 해제해도 자식은 무효화되지 않으며, 리스트를 만들 때 자식은 복사되고 소유권은 호출자에게 남습니다.

읽기 메서드는 여러 스레드에서 동시에 실행할 수 있습니다. 해제는 진행 중인 읽기가 끝날 때까지 기다린 뒤 네이티브 메모리를 해제합니다.

var limits = new SecsLimits(4096, 1024, 32, 8);
using var label = SecsItem.FromAscii("Temperature", limits);
using var values = SecsItem.FromF8(new double[] { 23.5, -0.0 }, limits);
using var source = SecsItem.CreateList(new[] { label, values }, limits);
byte[] encoded = source.Encode();
using var decoded = SecsItem.Decode(encoded, limits);
using var decodedLabel = decoded.GetChild(0);
Console.WriteLine(decodedLabel.GetAscii());

멤버

CreateList

메서드

기존 아이템의 복사본으로 리스트 아이템을 만듭니다.

public static SecsItem CreateList(ReadOnlySpan<SecsItem> children, SecsLimits limits)

매개변수

이름설명
children순서대로 나열한 자식 아이템입니다. 비어 있을 수 있습니다. 자식은 복사되며 소유권은 호출자에게 남습니다.
limits복사된 모든 자식을 포함하여 새 리스트가 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • ArgumentException 예외: children의 요소가 null입니다.
  • ObjectDisposedException 예외: 자식 아이템이 해제되었습니다.
  • PdcommException 예외: 리스트가 limits를 초과합니다(PdcommStatus.LimitExceeded).

Decode

메서드

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

public static SecsItem Decode(ReadOnlySpan<byte> data, SecsLimits limits)

매개변수

이름설명
data인코딩된 아이템입니다. 형식 바이트, 길이 바이트, 페이로드로 구성되며 뒤에 남는 바이트가 없어야 합니다.
limits디코딩된 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 입력이 불완전하거나(PdcommStatus.Truncated), 형식이 잘못되었거나 뒤에 추가 바이트가 있거나(PdcommStatus.InvalidData), limits를 초과합니다(PdcommStatus.LimitExceeded). PdcommException.ErrorOffset이 실패한 필드의 시작을 알려 줍니다.

Dispose

메서드

아이템의 네이티브 메모리를 해제합니다.

public void Dispose()

이 메서드를 여러 번 호출해도 효과가 없습니다. 이 아이템에서 복사한 아이템은 계속 유효합니다.

Encode

메서드

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

public byte[] Encode()

반환값

인코딩된 아이템을 담은 새 배열입니다. 길이 헤더는 최소 크기를 사용하며, 페이로드 바이트는 그대로 보존됩니다.

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.
  • PdcommException 예외: 네이티브 인코더가 실패했습니다.

FromAscii

메서드

텍스트로 SecsFormat.Ascii 아이템을 만듭니다.

public static SecsItem FromAscii(string value, SecsLimits limits)

매개변수

이름설명
value텍스트입니다. 모든 문자는 7비트 ASCII(U+0000~U+007F)여야 합니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • ArgumentNullException 예외: value가 null입니다.
  • ArgumentException 예외: value에 U+007F보다 큰 문자가 있습니다.
  • PdcommException 예외: 텍스트가 limits를 초과합니다(PdcommStatus.LimitExceeded).

FromBinary

메서드

원시 바이트로 SecsFormat.Binary 아이템을 만듭니다.

public static SecsItem FromBinary(ReadOnlySpan<byte> values, SecsLimits limits)

매개변수

이름설명
values저장할 바이트입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded).

FromBoolean

메서드

Boolean 값으로 SecsFormat.Boolean 아이템을 만듭니다. 값마다 1바이트이며 true는 1, false는 0입니다.

public static SecsItem FromBoolean(ReadOnlySpan<bool> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromF4

메서드

Single IEEE 754 값으로 빅 엔디언 SecsFormat.F4 아이템을 만듭니다.

public static SecsItem FromF4(ReadOnlySpan<float> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromF8

메서드

Double IEEE 754 값으로 빅 엔디언 SecsFormat.F8 아이템을 만듭니다.

public static SecsItem FromF8(ReadOnlySpan<double> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromI1

메서드

SByte 부호 있는 정수로 SecsFormat.I1 아이템을 만듭니다.

public static SecsItem FromI1(ReadOnlySpan<sbyte> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromI2

메서드

Int16 부호 있는 정수로 빅 엔디언 SecsFormat.I2 아이템을 만듭니다.

public static SecsItem FromI2(ReadOnlySpan<short> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromI4

메서드

Int32 부호 있는 정수로 빅 엔디언 SecsFormat.I4 아이템을 만듭니다.

public static SecsItem FromI4(ReadOnlySpan<int> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromI8

메서드

Int64 부호 있는 정수로 빅 엔디언 SecsFormat.I8 아이템을 만듭니다.

public static SecsItem FromI8(ReadOnlySpan<long> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromJis8

메서드

JIS-8로 인코딩된 바이트로 SecsFormat.Jis8 아이템을 만듭니다.

public static SecsItem FromJis8(ReadOnlySpan<byte> values, SecsLimits limits)

매개변수

이름설명
values그대로 저장되는 JIS-8 바이트입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded).

FromU1

메서드

Byte 부호 없는 정수로 SecsFormat.U1 아이템을 만듭니다.

public static SecsItem FromU1(ReadOnlySpan<byte> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromU2

메서드

UInt16 부호 없는 정수로 빅 엔디언 SecsFormat.U2 아이템을 만듭니다.

public static SecsItem FromU2(ReadOnlySpan<ushort> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromU4

메서드

UInt32 부호 없는 정수로 빅 엔디언 SecsFormat.U4 아이템을 만듭니다.

public static SecsItem FromU4(ReadOnlySpan<uint> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

FromU8

메서드

UInt64 부호 없는 정수로 빅 엔디언 SecsFormat.U8 아이템을 만듭니다.

public static SecsItem FromU8(ReadOnlySpan<ulong> values, SecsLimits limits)

매개변수

이름설명
values순서대로 인코딩할 값입니다. 비어 있을 수 있습니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • PdcommException 예외: 페이로드가 limits를 초과합니다(PdcommStatus.LimitExceeded). 네이티브 메모리를 할당하기 전에 검사합니다.

GetAscii

메서드

ASCII 아이템의 텍스트를 읽습니다.

public string GetAscii()

반환값

페이로드 바이트마다 하나씩인 아이템의 문자입니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.Ascii가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetBinary

메서드

Binary 아이템의 값을 원시 바이트로 읽습니다.

public byte[] GetBinary()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.Binary가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetBoolean

메서드

Boolean 아이템의 값을 Boolean 값으로 읽습니다. 0이 아닌 바이트는 모두 true입니다.

public bool[] GetBoolean()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.Boolean이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetChild

메서드

리스트 아이템의 자식 하나를 복사합니다.

public SecsItem GetChild(nuint index)

매개변수

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

반환값

호출자가 소유하며 해제해야 하는 독립된 새 아이템입니다.

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.
  • PdcommException 예외: 아이템이 리스트가 아니거나(PdcommStatus.InvalidArgument), index가 리스트의 SecsInfo.Count보다 작지 않습니다(PdcommStatus.OutOfRange).

GetF4

메서드

F4 아이템의 값을 Single 값으로 읽습니다.

public float[] GetF4()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.F4가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetF8

메서드

F8 아이템의 값을 Double 값으로 읽습니다.

public double[] GetF8()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.F8이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetI1

메서드

I1 아이템의 값을 SByte 값으로 읽습니다.

public sbyte[] GetI1()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.I1이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetI2

메서드

I2 아이템의 값을 Int16 값으로 읽습니다.

public short[] GetI2()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.I2가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetI4

메서드

I4 아이템의 값을 Int32 값으로 읽습니다.

public int[] GetI4()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.I4가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetI8

메서드

I8 아이템의 값을 Int64 값으로 읽습니다.

public long[] GetI8()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.I8이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetInfo

메서드

아이템의 형식, 요소 수, 인코딩 크기, 트리 형태를 가져옵니다.

public SecsInfo GetInfo()

반환값

아이템의 형태입니다.

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetJis8

메서드

Jis8 아이템의 값을 JIS-8 바이트 그대로 읽습니다.

public byte[] GetJis8()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.Jis8이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetPayload

메서드

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

public byte[] GetPayload()

반환값

전송 시 인코딩된 그대로의 페이로드를 담은 새 배열입니다(숫자 형식은 빅 엔디언).

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.
  • PdcommException 예외: 아이템이 리스트입니다(PdcommStatus.InvalidArgument).

GetU1

메서드

U1 아이템의 값을 Byte 값으로 읽습니다.

public byte[] GetU1()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.U1이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetU2

메서드

U2 아이템의 값을 UInt16 값으로 읽습니다.

public ushort[] GetU2()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.U2가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetU4

메서드

U4 아이템의 값을 UInt32 값으로 읽습니다.

public uint[] GetU4()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.U4가 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

GetU8

메서드

U8 아이템의 값을 UInt64 값으로 읽습니다.

public ulong[] GetU8()

반환값

디코딩된 값을 담은 새 배열입니다. 아이템에 값이 없으면 비어 있습니다.

참고

  • InvalidOperationException 예외: 아이템의 형식이 SecsFormat.U8이 아닙니다.
  • ObjectDisposedException 예외: 아이템이 해제되었습니다.

Primitive

메서드

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

public static SecsItem Primitive(SecsFormat format, ReadOnlySpan<byte> data, SecsLimits limits)

매개변수

이름설명
format아이템 형식입니다. SecsFormat.List를 제외한 모든 형식을 사용할 수 있습니다.
data전송 시 나타나는 그대로의 페이로드 바이트입니다. 숫자 형식은 빅 엔디언이어야 하고, 형식 너비의 정수배 요소여야 하며, SecsFormat.Ascii는 7비트 문자만 포함해야 합니다.
limits새 아이템이 충족해야 하는 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 아이템입니다.

참고

  • ArgumentException 예외: format이 SecsFormat.List입니다.
  • PdcommException 예외: format이 SECS-II 형식 코드가 아니거나(PdcommStatus.InvalidArgument), 페이로드가 형식에 맞지 않거나(PdcommStatus.InvalidData), limits를 초과합니다(PdcommStatus.LimitExceeded).

TryCopyPayload

메서드

호출자가 제공한 범위가 충분히 크면 기본 아이템의 원시 페이로드 바이트를 그 범위에 복사합니다.

public bool TryCopyPayload(Span<byte> destination, out nuint required)

매개변수

이름설명
destination페이로드를 받는 범위입니다.
required이 메서드가 반환될 때 페이로드 크기(바이트)를 담습니다.

반환값

페이로드를 복사했으면 true이고, destination이 너무 작으면 false입니다. 이 경우 destination은 바뀌지 않습니다.

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.
  • PdcommException 예외: 아이템이 리스트입니다(PdcommStatus.InvalidArgument).

TryEncode

메서드

호출자가 제공한 범위가 충분히 크면 아이템을 그 범위에 인코딩합니다.

public bool TryEncode(Span<byte> destination, out nuint required)

매개변수

이름설명
destination인코딩된 아이템을 받는 범위입니다.
required이 메서드가 반환될 때 인코딩 크기(바이트)를 담습니다.

반환값

아이템을 인코딩했으면 true이고, destination이 너무 작으면 false입니다. 이 경우 destination은 바뀌지 않습니다.

참고

  • ObjectDisposedException 예외: 아이템이 해제되었습니다.
  • PdcommException 예외: 대상이 짧은 것 외의 이유로 네이티브 인코더가 실패했습니다.

개인정보 처리방침