Module msrpce

Contains type definitions for RPCE data types.

Description

Contains type definitions for RPCE data types.

Most of these data types have shorter aliases, which are available by including types.hrl and records.hrl:


-include_lib("msrpce/include/records.hrl").
-include_lib("msrpce/include/types.hrl").

All types have at least their own name aliased by types.hrl, so e.g. msrpce:uint8() is aliased as uint8() with no module qualifier. These implied aliases are not shown in the tables below.

Base integer types (and their aliases)

TypeSignedWidth (bits)Aliases
msrpce:uint8() no 8 uchar(), byt(), usmall()
msrpce:uint16() no 16 word(), ushort(), wchar()
msrpce:uint32() no 32 ulong(), dword()
msrpce:uint64() no 64 uhyper(), qword()
msrpce:int8() yes 8 chr(), small()
msrpce:int16() yes 16 word(), short()
msrpce:int32() yes 32 long()
msrpce:int64() yes 64 hyper()

String and binary types (and their aliases)

TypeErlang typeConformantVaryingEncodingAliases
msrpce:bin() binary yes yes Raw bytes
msrpce:varying_bin() binary no yes Raw bytes
msrpce:fixed_bin() binary no no Raw bytes (fixed length)
msrpce:aligned_bin() binary no no Raw bytes (fixed length and alignment)
msrpce:str() string (list or binary) yes yes UTF-8 lpstr() (pointer)
msrpce:varying_str() string (list or binary) no yes UTF-8
msrpce:unicode() string (list or binary) yes yes UTF16-LE lpwstr() (pointer)
msrpce:varying_unicode() string (list or binary) no yes UTF16-LE
msrpce:uuid() binary (128-bit) no no Raw bytes (4-byte aligned)

Array types

Array types take another MSRPCE type as an argument, and represent an array of that underlying type. In Erlang, they are used as a list.

For example, msrpce:array(msrpce:uint16()) is a conformant-varying array of 16-bit unsigned integers. In Erlang it could be set to e.g. [1,2,3].

TypeConformantVaryingAliases
msrpce:array() yes yes
msrpce:conformant_array() yes no
msrpce:varying_array() no yes
msrpce:fixed_array() no no

Pointers

There is a single pointer type, msrpce:pointer(), which takes any RPCE type as an argument. It represents just the reference pointer itself (no length or size information). It is always nullable (NULL is represented by the Erlang atom undefined).

If you have a pointer with size information next to it, the annotation types msrpce:size_of() and msrpce:length_of() can be used to automatically set it. It will still require a separate field in your record.

Annotation types

These types wrap another RPCE type and change its behaviour.

TypeCan wrapSummary
msrpce:be() Any type Changes the wrapped type to big-endian representation
msrpce:le() Any type Changes the wrapped type to little-endian representation
msrpce:size_of() Integer type (other field can be any pointer, array or string) Replaces the value of the wrapped integer with the serialized size of another struct field
msrpce:length_of() Integer type (other field can be any array or string) Replaces the value of the wrapped integer with the array length of another struct field
msrpce:bitset() Integer type Represents an integer unpacked to a Map of bit fields
msrpce:bitset_mask() Integer type Like bitset() but uses masks, not bit numbers
msrpce:custom() Any type Passes the wrapped type through a custom decode/encode function

Other built-in compound types

These types are defined in types.hrl and may only be used by their bare names, after including that header.

TypeSerializationErlang representationSummary
sid() SID msrpce:sid() A MS Security Identifier (SID), e.g. [1,5,...]
rpc_unicode_str() struct string() A RPC_UNICODE_STRING structure
filetime() uint32 msrpce:filetime() File modification timestamp (also used for other timestamps)
ntstatus() uint32 msrpce:ntstatus() Generic status code format used by many parts of Windows
multi_string() pointer(array(uint8())) [string()] Multiple zero-terminated UTF8 strings, with a double-zero-terminator at the end (msz)
multi_unicode() pointer(array(uint16())) [string()] Multiple zero-terminated UTF16 strings, with a double-zero-terminator (4 bytes) at the end
rpc_multi_sz() struct [string()] A RPC_MULTI_SZ structure, containing a multi-string

Data Types

aligned_bin()

aligned_bin(_N, _Align) = binary()

Same as fixed_bin(N) but with the specified alignment. This is a useful "escape hatch" for custom types.

array()

array(T) = [T]

A conformant-varying array (the most commonly used kind)

be()

be(T) = T

Forces the inner type to be big-endian always (ignores the stream endian option).

bin()

bin() = binary()

A conformant-varying binary string, with no terminator. Conformant string maximum lengths are not hoisted.

bitnum()

bitnum() = integer()

Bit number, starting at 0 for LSB.

bitset()

bitset(_Base, BitName, _BitMap) = #{BitName => boolean()}

An integer which is made up of bits, each representing a boolean flag.

Base Any unsigned integer type (e.g. msrpce:uint32()) The actual serialised format of this field
BitName Union of atom types (e.g. bit_a | bit_b) All the possible bit names used in this set
BitMap msrpce:bitset_bitmap() (e.g. #{bit_a => 5, bit_b => 0}) Map of bit name => bit number

Example


-type field() :: msrpce:bitset(
    msrpce:uint32(),
    bit_a | bit_b,
    #{bit_a => 0, bit_b => 5}).
 
-record(thing, {
    bar :: field()
    }).
-msrpce_struct(thing).
 
#thing{bar = #{bit_a => true}}   % => encoded as 0x00000001
#thing{bar = #{bit_b => true}}   % => encoded as 0x00000020

bitset_bitmap()

bitset_bitmap() = #{atom() => bitnum()}

The type of the BitMap argument to bitset().

bitset_mask()

bitset_mask(_Base, BitName, _MaskMap) = #{BitName => boolean()}

Like a bitset() but the map takes masks rather than bit numbers.

Example


-type field() :: msrpce:bitset_mask(
    msrpce:uint32(),
    bit_a | bit_b,
    #{bit_a => 16#00100000, bit_b => 16#00000020}).
 
-record(thing, {
    bar :: field()
    }).
-msrpce_struct(thing).
 
#thing{bar = #{bit_a => true, bit_b => true}}   % => encoded as 0x00100020

bitset_maskmap()

bitset_maskmap() = #{atom() => mask()}

The type of the MaskMap argument to bitset_mask().

builtin()

builtin(_Base, RealType, _Encoder, _Decoder) = RealType

An extension type defined in the msrpce module.

conformant_array()

conformant_array(T) = [T]

A conformant array (has "maximum" length, offset and real length, then the data). Maximum length may be hoisted.

custom()

custom(_Base, RealType, _Encoder, _Decoder) = RealType

Defines a custom extension to a base RPC type.

Base The base RPCE type (e.g. msrpce:uint16())
RealType Actual Erlang type of the final decoded value.
Encoder Atom name of an arity-1 function which encodes the value (takes a value of type RealType and converts to type Base).
Decoder Atom name of an arity-1 function which decodes the value (takes a value of type Base and converts to type RealType).

Example


-type thing() :: msrpce:custom(uint8(), {integer(), integer()},
    encode_thing, decode_thing).
 
encode_thing({A, B}) -> A + B * 10.
decode_thing(Sum) -> {Sum rem 10, Sum div 10}.
 
-record(foobar, { field :: thing() }).
-msrpce_struct(foobar).
 
#foobar{field = {1,3}}       % => encoded as a uint8 of value 13

filetime()

filetime() = null | never | {integer(), time_unit()}

Common time specification format used in MSRPCE

fixed_array()

fixed_array(_N, T) = [T]

A fixed-size array with no length integer included. The first argument (N) should be the length as an integer.

fixed_bin()

fixed_bin(_N) = binary()

A fixed-length binary inserted into the stream with alignment 1 and no length integer attached.

int16()

int16() = integer()

A signed 16-bit integer

int32()

int32() = integer()

A signed 32-bit integer

int64()

int64() = integer()

A signed 64-bit integer

int8()

int8() = integer()

A signed 8-bit integer

le()

le(T) = T

Forces the inner type to be little-endian always (ignores the stream endian options).

length_of()

length_of(_Field, IntType) = IntType

An integer type which represents the array length of a sibling field in the same struct. It will be automatically calculated during encoding.

mask()

mask() = integer()

Bit mask, represented as an integer that will be bitwise-OR'd into the value if this bit is set.

ntstatus()

ntstatus() = {ntstatus:severity(), ntstatus:code() | integer()}

windows NT status return value

pointer()

pointer(T) = undefined | T

A pointer to any RPCE type. A 32-bit pointer value is included in the stream and then the actual content of it is serialised at the end.

Pointer values are generated as either 16#00000000 (the NULL value for undefined) or 16#00020000 bor (Index bsl 2) to match the behaviour of the MS IDL compiler in most common cases.

sid()

sid() = [integer()]

A Microsoft Security Identifier (SID) in numeric form (e.g. [1,5,1234,123])

size_of()

size_of(_Field, IntType) = IntType

An integer type which represents the encoded byte size of a sibling field in the same struct. It will be automatically calculated during encoding.

str()

str() = string()

A conformant-varying UTF8 string.

string_uuid()

string_uuid() = string()

A UUID in string hex form (e.g. "5e8cb9bc-bbc2-38b2-afc9-a9218c3b1d9c")

time_unit()

time_unit() = decimicrosecond | microsecond | millisecond | second

uint16()

uint16() = integer()

An unsigned 16-bit integer

uint32()

uint32() = integer()

An unsigned 32-bit integer (also known as a ulong or dword)

uint64()

uint64() = integer()

An unsigned 64-bit integer

uint8()

uint8() = integer()

An unsigned 8-bit integer

unicode()

unicode() = string()

A conformant-varying UTF16-LE string.

uuid()

uuid() = aligned_bin(16, 4)

A UUID in binary form

varying_array()

varying_array(T) = [T]

A varying array (has only a "maximum" length and then the data)

varying_bin()

varying_bin() = binary()

A varying binary string.

varying_str()

varying_str() = string()

A varying UTF8 string.

varying_unicode()

varying_unicode() = string()

A varying UTF16-LE string.

Function Index

decode_ntstatus/1Converts an NTSTATUS value from integer to atom/tuple form.
encode_ntstatus/1Converts an NTSTATUS value from atom/tuple form to an integer.
uuid_from_string/1Parses a hex-string-format UUID and returns a binary.
uuid_to_string/1Converts a UUID to the standard hex string format.

Function Details

decode_ntstatus/1

decode_ntstatus(Int::uint32()) -> ntstatus()

Converts an NTSTATUS value from integer to atom/tuple form.

encode_ntstatus/1

encode_ntstatus(X1::ntstatus()) -> uint32()

Converts an NTSTATUS value from atom/tuple form to an integer.

uuid_from_string/1

uuid_from_string(Str0::string_uuid()) -> uuid()

Parses a hex-string-format UUID and returns a binary.

uuid_to_string/1

uuid_to_string(X1::uuid()) -> string_uuid()

Converts a UUID to the standard hex string format.


Generated by EDoc