From 1d5a7501bbf2a33c60b24a71254b0c42939568aa Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Mon, 29 Oct 2018 00:49:56 +0100 Subject: sid.mli: document module --- sid.mli | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/sid.mli b/sid.mli index cffc0e9..9012df8 100644 --- a/sid.mli +++ b/sid.mli @@ -2,26 +2,54 @@ type t type sub_auths = Stdint.Uint32.t array + +val create : ?sa:Stdint.Uint32.t array -> Stdint.Uint64.t -> t option +(** [create sas ia] constructs a SID with the identifier authority [ia] + and, optionally, the subauthorities [sas]. The operation will return + [None] if [sa] contains more than fifteen subauthorities. *) + val create_unsafe : Stdint.Uint32.t array -> Stdint.Uint64.t -> t -val create : ?sa:Stdint.Uint32.t array -> Stdint.Uint64.t -> t -val equal_sub_auths : Stdint.Uint32.t array -> Stdint.Uint32.t array -> bool +(** [create_unsafe sas ia] constructs a SID with the identifier authority [ia] + and, optionally, the sub authorities [sas] without validating the inputs. + Use with caution. *) + val equal : t -> t -> bool +(** [equal sa sb] tests whether [sa] and [sb] are identical. *) + +val equal_sub_auths : Stdint.Uint32.t array -> Stdint.Uint32.t array -> bool +(** [equal_sub_auths sa sb] tests whether [sa] and [sb] have identical + subauthorities. *) + val get_ident_auth : t -> Stdint.Uint64.t +(** [get_ident_auth s] get the identifier authority of SID [s]. *) + val get_sub_auths : t -> sub_auths +(** [get_ident_auth s] get the subauthorities array of SID [s]. *) +(** Conversions to and from the {e string format syntax} (MS-DTYP 2.4.2.1). *) module StringFmt : sig val decode : string -> (t, string) result + (** [decode b] parse string buffer [b] into a SID. *) + val encode : t -> string + (** [encode s] convert SID [s] to its string representation. *) end +(** Conversion to and from the {e packet representation} (MS-DTYP 2.4.2.2). *) module PacketRep : sig type endian = Big | Little - val encode : ?endian:endian -> t -> bytes val decode : ?endian:endian -> bytes -> (t, string) result + (** [decode endian b] decode the byte buffer [b] as a SID. *) + + val encode : ?endian:endian -> t -> bytes + (** [encode endian s] convert SID [s] to the packet representation + encoding subauthorities in endianness [endian]. *) end +(** Pre-defined SID constansts and constructors with fixed identifier + authority (MS-DTYP 2.4.2.4). *) module WellKnown : sig val null : t @@ -49,5 +77,8 @@ module WellKnown : end val of_string : string -> (t, string) result +(** [of_string b] is an alias for [StringFmt.decode b]. *) + val to_string : t -> string +(** [to_string s] is an alias for [StringFmt.encode s]. *) -- cgit v1.2.3