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.
Type | Signed | Width (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() |
Type | Erlang type | Conformant | Varying | Encoding | Aliases |
---|---|---|---|---|---|
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 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]
.
Type | Conformant | Varying | Aliases |
---|---|---|---|
msrpce:array() |
yes | yes | |
msrpce:conformant_array() |
yes | no | |
msrpce:varying_array() |
no | yes | |
msrpce:fixed_array() |
no | no |
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.
These types wrap another RPCE type and change its behaviour.
Type | Can wrap | Summary |
---|---|---|
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 |
These types are defined in types.hrl
and may only be used
by their bare names, after including that header.
Type | Serialization | Erlang representation | Summary |
---|---|---|---|
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 |
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(T) = [T]
A conformant-varying array (the most commonly used kind)
be(T) = T
Forces the inner type to be big-endian always (ignores the stream endian option).
bin() = binary()
A conformant-varying binary string, with no terminator. Conformant string maximum lengths are not hoisted.
bitnum() = integer()
Bit number, starting at 0 for LSB.
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 |
-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() = #{atom() => bitnum()}
The type of the BitMap
argument to bitset()
.
bitset_mask(_Base, BitName, _MaskMap) = #{BitName => boolean()}
Like a bitset()
but the map takes masks rather than bit numbers.
-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() = #{atom() => mask()}
The type of the MaskMap
argument to bitset_mask()
.
builtin(_Base, RealType, _Encoder, _Decoder) = RealType
An extension type defined in the msrpce
module.
conformant_array(T) = [T]
A conformant array (has "maximum" length, offset and real length, then the data). Maximum length may be hoisted.
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 ). |
-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() = null | never | {integer(), time_unit()}
Common time specification format used in MSRPCE
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(_N) = binary()
A fixed-length binary inserted into the stream with alignment 1 and no length integer attached.
int16() = integer()
A signed 16-bit integer
int32() = integer()
A signed 32-bit integer
int64() = integer()
A signed 64-bit integer
int8() = integer()
A signed 8-bit integer
le(T) = T
Forces the inner type to be little-endian always (ignores the stream endian options).
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() = integer()
Bit mask, represented as an integer that will be bitwise-OR'd into the value if this bit is set.
ntstatus() = {ntstatus:severity(), ntstatus:code() | integer()}
windows NT status return value
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 either16#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() = [integer()]
A Microsoft Security Identifier (SID) in numeric form (e.g. [1,5,1234,123])
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() = string()
A conformant-varying UTF8 string.
string_uuid() = string()
A UUID in string hex form (e.g. "5e8cb9bc-bbc2-38b2-afc9-a9218c3b1d9c")
time_unit() = decimicrosecond | microsecond | millisecond | second
uint16() = integer()
An unsigned 16-bit integer
uint32() = integer()
An unsigned 32-bit integer (also known as a ulong
or dword
)
uint64() = integer()
An unsigned 64-bit integer
uint8() = integer()
An unsigned 8-bit integer
unicode() = string()
A conformant-varying UTF16-LE string.
uuid() = aligned_bin(16, 4)
A UUID in binary form
varying_array(T) = [T]
A varying array (has only a "maximum" length and then the data)
varying_bin() = binary()
A varying binary string.
varying_str() = string()
A varying UTF8 string.
varying_unicode() = string()
A varying UTF16-LE string.
decode_ntstatus/1 | Converts an NTSTATUS value from integer to atom/tuple form. |
encode_ntstatus/1 | Converts an NTSTATUS value from atom/tuple form to an integer. |
uuid_from_string/1 | Parses a hex-string-format UUID and returns a binary. |
uuid_to_string/1 | Converts a UUID to the standard hex string format. |
decode_ntstatus(Int::uint32()) -> ntstatus()
Converts an NTSTATUS value from integer to atom/tuple form.
encode_ntstatus(X1::ntstatus()) -> uint32()
Converts an NTSTATUS value from atom/tuple form to an integer.
uuid_from_string(Str0::string_uuid()) -> uuid()
Parses a hex-string-format UUID and returns a binary.
uuid_to_string(X1::uuid()) -> string_uuid()
Converts a UUID to the standard hex string format.
Generated by EDoc