winmd

README

Go winmd parser

A Windows Metadata (a.k.a. winmd) parser written in Go and based on the ECMA-335 6th edition standard.

Development References

These resources are useful as reference while working on the go-winmd module:

• ECMA-335 specification
• microsoft/win32metadata GitHub repository
• Windows Runtime (WinRT) document on Windows Metadata
• .NET System.Reflection.Metadata implementation
• go.dev/issue/43838 "x/sys/windows: use win32metadata?"

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Documentation

Overview

Package winmd implements a parser for Windows Metadata (WinMD). The reference document is ECMA-335 6th edition, which can be located at https://www.ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf.

Documentation and comments referencing an ECMA-335 section are prefixed with the symbol §.

Copyright (c) Microsoft Corporation. Licensed under the MIT License.

Index

• type Assembly
• type AssemblyRef
• type BlobHeap
  • func (bh BlobHeap) Bytes(start uint32) ([]byte, error)
• type ClassLayout
• type CodedIndex
• type Constant
• type CustomAttribute
• type DeclSecurity
• type Event
• type EventMap
• type ExportedType
• type Field
• type FieldLayout
• type FieldMarshal
• type FieldRVA
• type File
• type GUIDHeap
  • func (gh GUIDHeap) GUID(idx uint32) ([16]byte, error)
• type GenericParam
• type GenericParamConstraint
• type ImplMap
• type Index
• type InterfaceImpl
• type ManifestResource
• type MemberRef
• type Metadata
  • func New(pefile *pe.File) (*Metadata, error)
  • func (m *Metadata) FieldSignature(bytes SigFieldBlob) (SigField, error)
  • func (m *Metadata) MethodDefSignature(data SigMethodDefBlob) (SigMethodDef, error)
• type MethodDef
• type MethodImpl
• type MethodSemantics
• type MethodSpec
• type Module
• type ModuleRef
• type NestedClass
• type Param
• type Property
• type PropertyMap
• type Record
• type SigArray
• type SigConstraint
• type SigCustomMod
• type SigCustomModKind
• type SigField
• type SigFieldBlob
• type SigGenericInst
• type SigLocalVar
• type SigLocalVarKind
• type SigLocalVarMod
• type SigLocalVars
• type SigMethodDef
• type SigMethodDefBlob
• type SigMethodRef
• type SigMethodSpec
• type SigParam
• type SigParamKind
• type SigProperty
• type SigPropertyBlob
• type SigRetType
• type SigRetTypeKind
• type SigType
• type SigTypeSpec
• type Slice
• type StandAloneSig
• type String
  • func (s String) String() string
• type StringHeap
  • func (sh StringHeap) String(start uint32) (String, error)
• type Table
  • func (t Table[T, TP]) Record(row Index) (TP, error)
• type Tables
• type TypeDef
• type TypeRef
• type TypeSpec
• type USHeap

Types

type Assembly

type Assembly struct {
	HashAlgID      flags.AssemblyHashAlgorithm
	MajorVersion   uint16
	MinorVersion   uint16
	BuildNumber    uint16
	RevisionNumber uint16
	Flags          flags.AssemblyFlags
	PublicKey      []byte
	Name           String
	Culture        String
}

Assembly is defined in §II.22.2. @table=0x20

type AssemblyRef

type AssemblyRef struct {
	MajorVersion     uint16
	MinorVersion     uint16
	BuildNumber      uint16
	RevisionNumber   uint16
	Flags            flags.AssemblyFlags
	PublicKeyOrToken []byte
	Name             String
	Culture          String
	HashValue        []byte
}

AssemblyRef is defined in §II.22.5. @table=0x23

type BlobHeap

type BlobHeap []byte

BlobHeap provides access to the #Blob heap as defined in §II.24.2.4.

func (BlobHeap) Bytes

func (bh BlobHeap) Bytes(start uint32) ([]byte, error)

Bytes extracts data from the blob heap bh at offset start.

type ClassLayout

type ClassLayout struct {
	PackingSize uint16
	ClassSize   uint32
	Parent      Index // @ref=TypeDef
}

ClassLayout is defined in §II.22.8. @table=0x0F

type CodedIndex

type CodedIndex struct {
	Index Index
	Tag   int8
}

CodedIndex indexes a record on any table.

type Constant

type Constant struct {
	Type    flags.ElementType
	Padding byte       // 1-byte padding zero
	Parent  CodedIndex // @code=HasConstant
	Value   []byte
}

Constant is defined in §II.22.9. @table=0x0B

type CustomAttribute

type CustomAttribute struct {
	Parent CodedIndex // @code=HasCustomAttribute
	Type   CodedIndex // @code=CustomAttributeType
	Value  []byte
}

CustomAttribute is defined in §II.22.10. @table=0x0C

type DeclSecurity

type DeclSecurity struct {
	Action        uint16
	Parent        CodedIndex // @code=HasDeclSecurity
	PermissionSet []byte
}

DeclSecurity is defined in §II.22.11. @table=0x0E

type Event

type Event struct {
	EventFlags flags.EventAttributes
	Name       String
	EventType  CodedIndex // @code=TypeDefOrRef
}

Event is defined in §II.22.13. @table=0x14

type EventMap

type EventMap struct {
	Parent    Index // @ref=TypeDef
	EventList Slice // @ref=Event
}

EventMap is defined in §II.22.12. @table=0x12

type ExportedType

type ExportedType struct {
	Flags          flags.TypeAttributes
	TypeDefID      uint32 // index into a TypeDef table, used as hint only
	Name           String
	Namespace      String
	Implementation CodedIndex // @code=Implementation
}

ExportedType is defined in §II.22.14. @table=0x27

type Field

type Field struct {
	Flags     flags.FieldAttributes
	Name      String
	Signature SigFieldBlob
}

Field is defined in §II.22.15. @table=0x04

type FieldLayout

type FieldLayout struct {
	Offset uint32
	Field  Index // @ref=Field
}

FieldLayout is defined in §II.22.16. @table=0x10

type FieldMarshal

type FieldMarshal struct {
	Parent     CodedIndex // @code=HasFieldMarshal
	NativeType []byte
}

FieldMarshal is defined in §II.22.17. @table=0x0D

type FieldRVA

type FieldRVA struct {
	RVA   uint32
	Field Index // @ref=Field
}

FieldRVA is defined in §II.22.18. @table=0x1D

type File

type File struct {
	Flags     flags.FileAttributes
	Name      String
	HashValue []byte
}

File is defined in §II.22.19. @table=0x26

type GUIDHeap

type GUIDHeap []byte

GUIDHeap provides access to the #GUID heap as defined in §II.24.2.5.

func (GUIDHeap) GUID

func (gh GUIDHeap) GUID(idx uint32) ([16]byte, error)

GUID extracts the GUID from the guid heap gh at idx.

type GenericParam

type GenericParam struct {
	Number uint16
	Flags  flags.GenericParamAttributes
	Owner  CodedIndex // @code=TypeOrMethodDef
	Name   String
}

GenericParam is defined in §II.22.20. @table=0x2A

type GenericParamConstraint

type GenericParamConstraint struct {
	Owner      Index      // @ref=GenericParam
	Constraint CodedIndex // @code=TypeDefOrRef
}

GenericParam is defined in §II.22.21. @table=0x2C

type ImplMap

type ImplMap struct {
	MappingFlags    flags.PInvokeAttributes
	MemberForwarded CodedIndex // @code=MemberForwarded
	ImportName      String
	ImportScope     Index // @ref=ModuleRef
}

ImplMap is defined in §II.22.22. @table=0x1C

type Index

type Index uint32

Index indexes a record in a table.

type InterfaceImpl

type InterfaceImpl struct {
	Class     Index      // @ref=TypeDef
	Interface CodedIndex // @code=TypeDefOrRef
}

InterfaceImpl is defined in §II.22.23. @table=0x09

type ManifestResource

type ManifestResource struct {
	Offset         uint32
	Flags          flags.ManifestResourceAttributes
	Name           String
	Implementation CodedIndex // @code=Implementation
}

ManifestResource is defined in §II.22.24. @table=0x28

type MemberRef

type MemberRef struct {
	Class     CodedIndex // @code=MemberRefParent
	Name      String
	Signature []byte
}

MemberRef is defined in §II.22.25. @table=0x0A

type Metadata

type Metadata struct {
	Version string
	Tables  *Tables
	Strings StringHeap
	US      USHeap
	Blob    BlobHeap
	GUID    GUIDHeap
	// contains filtered or unexported fields
}

A Metadata represents an open Windows Metadata file.

func New

func New(pefile *pe.File) (*Metadata, error)

New creates a new File from an underlying PE file.

func (*Metadata) FieldSignature

func (m *Metadata) FieldSignature(bytes SigFieldBlob) (SigField, error)

func (*Metadata) MethodDefSignature

func (m *Metadata) MethodDefSignature(data SigMethodDefBlob) (SigMethodDef, error)

type MethodDef

type MethodDef struct {
	RVA       uint32
	ImplFlags flags.MethodImplAttributes
	Flags     flags.MethodAttributes
	Name      String
	Signature SigMethodDefBlob
	ParamList Slice // @ref=Param
}

MethodDef is defined in §II.22.26. @table=0x06

type MethodImpl

type MethodImpl struct {
	Class             Index      // @ref=TypeDef
	MethodBody        CodedIndex // @code=MethodDefOrRef
	MethodDeclaration CodedIndex // @code=MethodDefOrRef
}

MethodImpl is defined in §II.22.27. @table=0x19

type MethodSemantics

type MethodSemantics struct {
	Semantics   flags.MethodSemanticsAttributes
	Method      Index      // @ref=MethodDef
	Association CodedIndex // @code=HasSemantics
}

MethodImpl is defined in §II.22.28. @table=0x18

type MethodSpec

type MethodSpec struct {
	Method        CodedIndex // @code=MethodDefOrRef
	Instantiation []byte
}

MethodSpec is defined in §II.22.29. @table=0x2B

type Module

type Module struct {
	Generation uint16
	Name       String
	Mvid       [16]byte
	EncID      [16]byte
	EncBaseID  [16]byte
}

Module is defined in §II.22.30. @table=0x00

type ModuleRef

type ModuleRef struct {
	Name String
}

ModuleRef is defined in §II.22.31. @table=0x1A

type NestedClass

type NestedClass struct {
	NestedClass    Index // @ref=TypeDef
	EnclosingClass Index // @ref=TypeDef
}

NestedClass is defined in §II.22.32. @table=0x29

type Param

type Param struct {
	Flags    flags.ParamAttributes
	Sequence uint16
	Name     String
}

Param is defined in §II.22.33. @table=0x08

type Property

type Property struct {
	Flags flags.PropertyAttributes
	Name  String
	Type  SigPropertyBlob
}

Property is defined in §II.22.34. @table=0x17

type PropertyMap

type PropertyMap struct {
	Parent       Index // @ref=TypeDef
	PropertyList Slice // @ref=Property
}

PropertyMap is defined in §II.22.35. @table=0x15

type Record

type Record[T any] interface {
	*T
	// contains filtered or unexported methods
}

Record is an item in a metadata table.

type SigArray

type SigArray struct {
	Type        SigType
	Rank        uint32
	Sizes       []uint32
	LowerBounds []int32
}

SigArray is a SigType with an ArrayShape, where ArrayShape is defined in §II.23.2.13.

type SigConstraint

type SigConstraint struct {
	Pinned bool
}

type SigCustomMod

type SigCustomMod struct {
	Kind  SigCustomModKind
	Index CodedIndex
}

SigCustomMod is defined in §II.23.2.7.

type SigCustomModKind

type SigCustomModKind uint8

const (
	SigCustomModKind_Opt SigCustomModKind = iota
	SigCustomModKind_Reqd
)

type SigField

type SigField struct {
	Type SigType
}

SigField is defined in §II.23.2.4.

type SigFieldBlob

type SigFieldBlob []byte

type SigGenericInst

type SigGenericInst struct {
	Class bool
	Index CodedIndex
	Type  []SigType
}

type SigLocalVar

type SigLocalVar struct {
	Kind SigLocalVarKind
	Mod  []SigLocalVarMod // empty if Kind is TypedByRef
	Type SigType          // empty if Kind is TypedByRef
}

type SigLocalVarKind

type SigLocalVarKind uint8

const (
	SigLocalVarKind_ByValue SigLocalVarKind = iota
	SigLocalVarKind_ByRef
	SigLocalVarKind_TypedByRef
)

type SigLocalVarMod

type SigLocalVarMod struct {
	Mod        *SigCustomMod
	Constraint SigConstraint
}

type SigLocalVars

type SigLocalVars []SigLocalVar

SigLocalVars is defined as "LocalVarSig" in §II.23.2.6. This type represents the type of all local vars in a method, and the name has been changed for clarity and to make it easier to name "SigLocalVar".

type SigMethodDef

type SigMethodDef struct {
	HasThis      bool
	ExplicitThis bool
	VarArgs      bool
	Generic      uint32
	RetType      SigRetType
	Param        []SigParam
}

SigMethodDef is defined in §II.23.2.1.

type SigMethodDefBlob

type SigMethodDefBlob []byte

type SigMethodRef

type SigMethodRef struct {
	SigMethodDef
	VariableParam []Param
}

SigMethodRef is defined in §II.23.2.2.

type SigMethodSpec

type SigMethodSpec []SigType

SigMethodSpec is defined in §II.23.2.15

type SigParam

type SigParam struct {
	Kind SigParamKind
	Type SigType // empty if Kind is TypedByRef
}

SigParam is defined in §II.23.2.10.

type SigParamKind

type SigParamKind uint8

const (
	SigParamKind_ByValue SigParamKind = iota
	SigParamKind_ByRef
	SigParamKind_TypedByRef
)

type SigProperty

type SigProperty struct {
	HasThis bool
	SigField
	Param []SigParam
}

SigProperty is defined in §II.23.2.5.

type SigPropertyBlob

type SigPropertyBlob []byte

type SigRetType

type SigRetType struct {
	Kind SigRetTypeKind
	Type SigType // empty if Kind is TypedByRef or Void
}

SigRetType is defined in §II.23.2.11.

type SigRetTypeKind

type SigRetTypeKind uint8

const (
	SigRetTypeKind_ByValue SigRetTypeKind = iota
	SigRetTypeKind_ByRef
	SigRetTypeKind_TypedByRef
	SigRetTypeKind_Void
)

type SigType

type SigType struct {
	Kind  flags.ElementType
	Mod   []SigCustomMod
	Value any // optional
}

SigType is defined in §II.23.2.12.

type SigTypeSpec

type SigTypeSpec struct {
	Kind  flags.ElementType
	Value any
}

SigTypeSpec is defined in §II.23.2.14.

type Slice

type Slice struct {
	Start Index
	End   Index
}

Slice indexes the range of records [Start,End) on the table T.

type StandAloneSig

type StandAloneSig struct {
	Signature []byte
}

StandAloneSig is defined in §II.22.36. @table=0x11

type String

type String struct {
	// Start is the offset in the #Strings heap where the string starts. This is the parameter that
	// was passed to StringHeap.String to create this String. The strings heap doesn't contain
	// duplicate strings, so this value can be used to uniquely identify strings that come from the
	// same heap.
	Start uint32
	// contains filtered or unexported fields
}

String is complete UTF8 string from the #String heap It does not contain the null-terminated character.

It is used as an optimization to avoid allocating when reading from the #Strings heap.

func (String) String

func (s String) String() string

type StringHeap

type StringHeap []byte

StringHeap provides access to #Strings heap as defined in §II.24.2.3.

func (StringHeap) String

func (sh StringHeap) String(start uint32) (String, error)

String extracts string from the string heap st at offset start.

type Table

type Table[T any, TP Record[T]] struct {
	Len uint32
	// contains filtered or unexported fields
}

Table is a record container as defined in §II.22.

func (Table[T, TP]) Record

func (t Table[T, TP]) Record(row Index) (TP, error)

Record returns the record at row.

type Tables

type Tables struct {
	Assembly               Table[Assembly, *Assembly]
	AssemblyRef            Table[AssemblyRef, *AssemblyRef]
	ClassLayout            Table[ClassLayout, *ClassLayout]
	Constant               Table[Constant, *Constant]
	CustomAttribute        Table[CustomAttribute, *CustomAttribute]
	DeclSecurity           Table[DeclSecurity, *DeclSecurity]
	EventMap               Table[EventMap, *EventMap]
	Event                  Table[Event, *Event]
	ExportedType           Table[ExportedType, *ExportedType]
	Field                  Table[Field, *Field]
	FieldLayout            Table[FieldLayout, *FieldLayout]
	FieldMarshal           Table[FieldMarshal, *FieldMarshal]
	FieldRVA               Table[FieldRVA, *FieldRVA]
	File                   Table[File, *File]
	GenericParam           Table[GenericParam, *GenericParam]
	GenericParamConstraint Table[GenericParamConstraint, *GenericParamConstraint]
	ImplMap                Table[ImplMap, *ImplMap]
	InterfaceImpl          Table[InterfaceImpl, *InterfaceImpl]
	ManifestResource       Table[ManifestResource, *ManifestResource]
	MemberRef              Table[MemberRef, *MemberRef]
	MethodDef              Table[MethodDef, *MethodDef]
	MethodImpl             Table[MethodImpl, *MethodImpl]
	MethodSemantics        Table[MethodSemantics, *MethodSemantics]
	MethodSpec             Table[MethodSpec, *MethodSpec]
	Module                 Table[Module, *Module]
	ModuleRef              Table[ModuleRef, *ModuleRef]
	NestedClass            Table[NestedClass, *NestedClass]
	Param                  Table[Param, *Param]
	Property               Table[Property, *Property]
	PropertyMap            Table[PropertyMap, *PropertyMap]
	StandAloneSig          Table[StandAloneSig, *StandAloneSig]
	TypeDef                Table[TypeDef, *TypeDef]
	TypeRef                Table[TypeRef, *TypeRef]
	TypeSpec               Table[TypeSpec, *TypeSpec]
}

Tables provides access to the tables and records stored in the #~ stream as defined in §II.24.2.6

type TypeDef

type TypeDef struct {
	Flags      flags.TypeAttributes
	Name       String
	Namespace  String
	Extends    CodedIndex // @code=TypeDefOrRef
	FieldList  Slice      // @ref=Field
	MethodList Slice      // @ref=MethodDef
}

TypeDef is defined in §II.22.37. @table=0x02

type TypeRef

type TypeRef struct {
	ResolutionScope CodedIndex // @code=ResolutionScope
	Name            String
	Namespace       String
}

TypeRef is defined in §II.22.38. @table=0x01

type TypeSpec

type TypeSpec struct {
	Signature []byte
}

TypeSpec is defined in §II.22.39. @table=0x1B

type USHeap

type USHeap []byte

USHeap provides access to the #US heap as defined in §II.24.2.4.