Crate oxirush_aper

Expand description

Aligned PER (ITU-T X.691, the ALIGNED variant of BASIC-PER) for generated bindings of 3GPP-style ASN.1: a reader, a writer, and the types of the values.

use oxirush_aper::{Reader, Writer};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut octets = Vec::new();
    let mut writer = Writer::new(&mut octets);
    // INTEGER (0..7): three bits
    writer.unsigned(5, 0, 7)?;
    // INTEGER (0..255, ...): the extension bit, then one octet, aligned
    writer.unsigned_extensible(200, 0, 255)?;
    // ENUMERATED with 6 root values and an extension marker: the fourth
    writer.index(3, 6, true);
    // SIZE (1..256) of a SEQUENCE OF: its count, then its items
    writer.size(2, 1, 256)?;
    writer.unsigned(1, 0, 1)?;
    writer.unsigned(0, 0, 1)?;
    println!("{octets:02x?}");

    let mut reader = Reader::new(&octets);
    println!("{}", reader.unsigned(0, 7)?);
    println!("{}", reader.unsigned_extensible(0, 255)?);
    println!("{}", reader.enumerated(6, 0, true)?);
    println!("{} items: {} {}", reader.size(1, 256)?, reader.bit()?, reader.bit()?);

    println!("{}", Writer::new(&mut Vec::new()).unsigned(8, 0, 7).unwrap_err());
    Ok(())
}

[a0, c8, 30, 01, 80]
5
200
3
2 items: true false
the value does not encode: 8 is outside its constraint (0..7)

§Tasks

The README has an example of each, with what it prints.

Task	Items
Write the codec of a type	`AsnType`, `Decode`, `Encode`, `decode`, `encode`, `encode_into`
Read and write the fields	`Reader`, `Writer`, `UNBOUNDED`
Bit strings	`Bits`, `BitString`
An open type	`Reader::open_type`, `Writer::begin_open_type`, `Writer::end_open_type`, `Octets`
Extension additions	`Reader::additions`, `Additions`, `Writer::additions`, `Reader::skip_additions`
What the reader accepts	`decode_with_faults`, `decode_strict`, `Fault`, `Reader::noting`
Check a PDU against the object set of its message	`check`
The macros and the readers of a protocol crate	`protocol`

A Reader and a Writer have a method for each field of X.691 that the two protocols of the family use. They work on octets where the encoding is aligned and on bits where it is not, the bounds of a constraint are their arguments, and a reader allocates nothing but the lists and the strings in fragments of what it reads.

The values are native numbers, arrays for an OCTET STRING of one size, Octets for the others and for an open type, Bits for a BIT STRING of 64 bits at most, BitString for a longer one, Cow<str> for a character string and ObjectIdentifier.

§The OxiRush family

oxirush-utils: the 3GPP identities, and the JSON tree with its paths that the others share.
oxirush-aper: aligned PER, the runtime of the NGAP and S1AP codecs.
oxirush-nas: the NAS messages of 5GS and EPS.
oxirush-security: NAS security, AKA and the derivation of keys.
oxirush-ngap: NGAP, between a gNB and an AMF.
oxirush-s1ap: S1AP, between an eNB and an MME.
oxirush-gtp-u: GTP-U tunnels, with a test UPF.
oxirush-sctp: SCTP sockets, which carry NGAP and S1AP.

Modules§

check: How a PDU of an application protocol of 3GPP compares with what its ASN.1 assigns its message: the criticality of its procedure, and the object set of the IEs of the message. The bindings of each protocol tell their deviations with their own types, which they give through Diagnostics: oxirush_ngap::Deviation is Deviation<oxirush_ngap::Ngap>.
jsoninspect: The values of generated bindings as trees of oxirush_utils::tree: a Value is written and read, and no text.
protocol: What the application protocols of 3GPP that are written in aligned PER have in common, as NGAP (TS 38.413) and S1AP (TS 36.413): a PDU of three directions holds the message of a procedure in an open type, a message is a container of protocol IEs, and each IE is its identifier, its criticality and its value in an open type. The ASN.1 gives each message the object set of the IEs that it can have.

Structs§

Additions: The extension additions of a SEQUENCE that a reader was given: which of them are present, in their order. Reader::additions gives it, and has an example.
BitString: A BIT STRING of any length: its octets, the last one padded with zero bits, and how many bits it has.
Bits: A BIT STRING of 64 bits at most: a number with a length.
Error: The error of every function of the crate that can fail, and of the bindings that are built on it.
ErrorIe: The IE of a message that an error is about: Error::ie of an error of the kind MissingIe or UndecodableIe that the bindings of a protocol made.
Faults: The faults of one reading, in the order of the octets. It is a list of Noted, which it derefs to: the first four, held in place without an allocation, and count says how many the reader met. It is empty for octets that are written by the clauses.
Noted: A fault that a reader noted, and where it is.
ObjectIdentifier: An OBJECT IDENTIFIER: its arcs.
Octets: The octets of an OCTET STRING or of an open type: borrowed from the octets that they were decoded from, or owned.
Reader: A reader of aligned PER: the octets of an encoding, and how far they are read.
Writer: A writer of aligned PER: it appends the fields of an encoding to the octets of its caller.

Enums§

Criticality: The criticality of an IE or of a procedure in the application protocols of 3GPP, as their ASN.1 has it (Criticality ::= ENUMERATED { reject, ignore, notify }): what a receiver does with what it does not comprehend. The bindings of a protocol have a type of their own for it, which converts to and from this one.
ErrorKind: What went wrong: the part of an Error that a caller matches on.
Fault: An encoding that X.691 gives one form for, in another: the value is whole, and a sender by the clause writes it otherwise. A reader takes it, as the encoder of a peer may write it, and notes it: see Reader::faults.

Constants§

UNBOUNDED: The upper bound of a size constraint that has none, as SIZE (1..MAX).

Traits§

AsnType: A type of an ASN.1 module. The example of Decode implements it.
Decode: A type whose values are read in aligned PER. 'a is how long the octets live that a value borrows from.
Encode: A type whose values are written in aligned PER. The example of Decode implements it.

Functions§

decode: The value of the type T that octets are the complete encoding of (X.691 §11.1): one value, whole, and no octet after it. What the value holds of octets and of strings is borrowed from octets.
decode_strict: The value of the type T that octets are the complete encoding of, when they are the one encoding that X.691 gives the value: what decode reads in another form, a Fault, is an error here. The counterpart of encode_strict.
decode_with_faults: The value of the type T that octets are the complete encoding of, as decode reads it, and what of the encoding is in another form than the one that X.691 gives it: the Faults of the reader, with the padding of the end among them. They are none for octets that are written by the clauses.
encode: The complete encoding of value (X.691 §11.1): its fields, zero bits up to the end of the last octet, and one zero octet for a value that has no field.
encode_into: Append the complete encoding of value to octets. After an error, octets are as they were.
encode_strict: The complete encoding of value, as encode gives it, for a value that is one of this version of its type: a number or a size outside the root of an extensible constraint, which encode writes as an extension, is an error.