fileversion

README

# go-fileversion

Package fileversion provides wrapper for querying properties from windows version-information resource.

Using the package you can extract the following info:

If you are looking how to add this info to your go binary - look at josephspurrier/goversioninfo.

Examples

Print version info from input file

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/bi-zone/go-fileversion"
)

func main() {
	if len(os.Args) < 2 {
		log.Fatalf("Usage: %s <image-path>", os.Args[0])
	}
	f, err := fileversion.New(os.Args[1])
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("ProductName:", f.ProductName())
	fmt.Println("LegalCopyright:", f.LegalCopyright())
	fmt.Println("Version:", f.FixedInfo().FileVersion)
}

All string properties in file version-information resource by-design has multiple translations. go-fileversion allows you to query that translations in a 2 ways.

You can create an Info object with "preferred" locale:

germanLocale := fileversion.Locale{
    LangID: 0x0407, // langID German
    CharsetID: fileversion.CSUnicode,
}
f, err := fileversion.NewWithLocale(os.Args[1], germanLocale)
if err != nil {
    log.Fatal(err)
}
fmt.Println("ProductName:", f.ProductName())

Here "German-Unicode" locale will be used to query string properties (like ProductName), but if the german translation will be missing - go-fileversion would try to fetch a property with default translation. (The idea of locales handling was copied from .NET Framework 4.8)

The only way to get necessary translation without any heuristics is to use GetPropertyWithLocale manualy:

f, err := fileversion.New(os.Args[1])
if err != nil {
    log.Fatal(err)
}
germanLocale := fileversion.Locale{
    LangID: 0x0407, // langID German
    CharsetID: fileversion.CSUnicode,
}
fmt.Println(f.GetPropertyWithLocale("ProductName", germanLocale))

Versioning

Project uses semantic versioning for version numbers, which is similar to the version contract of the Go language. Which means that the major version will always maintain backwards compatibility with minor versions. Minor versions will only add new additions and changes. Fixes will always be in patch.

This contract should allow you to upgrade to new minor and patch versions without breakage or modifications to your existing code. Leave a ticket, if there is breakage, so that it could be fixed.

Documentation

Overview

Package fileversion provides wrapper for querying properties from windows version-information resource.

fileversion API is aimed to the easiest way of getting file properties so it ignore most of errors querying properties. We suppose most of the time it will be used as "create with New and just access properties". If you need some guaranties - access the properties manually using GetProperty and GetPropertyWithLocale.

For more info about version-information resource look at https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource

Index

• Constants
• Variables
• type CharsetID
• type FileVersion
  • func (f FileVersion) String() string
• type FixedFileInfo
• type Info
  • func New(path string) (Info, error)
  • func NewWithLocale(path string, locale Locale) (Info, error)
  • func (f Info) Comments() string
  • func (f Info) CompanyName() string
  • func (f Info) FileDescription() string
  • func (f Info) FileVersion() string
  • func (f Info) FixedInfo() FixedFileInfo
  • func (f Info) GetProperty(propertyName string) (string, error)
  • func (f Info) GetPropertyWithLocale(propertyName string, locale Locale) (string, error)
  • func (f Info) InternalName() string
  • func (f Info) LegalCopyright() string
  • func (f Info) LegalTrademarks() string
  • func (f Info) OriginalFilename() string
  • func (f Info) PrivateBuild() string
  • func (f Info) ProductName() string
  • func (f Info) ProductVersion() string
  • func (f Info) SpecialBuild() string
• type LangID
• type Locale

Constants

const (
	LangEnglish = LangID(0x049)

	CSAscii   = CharsetID(0x04e4)
	CSUnicode = CharsetID(0x04B0)
	CSUnknown = CharsetID(0x0000)
)

The package defines a list of most commonly used LangID and CharsetID constant. More combinations you can find in windows docs or at https://godoc.org/github.com/josephspurrier/goversioninfo#pkg-constants

Variables

var DefaultLocales = []Locale{
	{
		LangID:    LangEnglish,
		CharsetID: CSAscii,
	},
	{
		LangID:    LangEnglish,
		CharsetID: CSUnicode,
	},
	{
		LangID:    LangEnglish,
		CharsetID: CSUnknown,
	},
}

DefaultLocales is a list of default Locale values. It's used as a fallback in a calls with automatic locales detection.

Types

type CharsetID

type CharsetID uint16

CharsetID is character-set identifier. Could be one of the codes listed in `charsetID` section of https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource

type FileVersion

type FileVersion struct {
	Major uint16
	Minor uint16
	Patch uint16
	Build uint16
}

FileVersion is a multi-component version.

func (FileVersion) String

func (f FileVersion) String() string

String returns a string representation of the version.

type FixedFileInfo

type FixedFileInfo struct {
	FileVersion    FileVersion
	ProductVersion FileVersion
	FileFlagsMask  uint32
	FileFlags      uint32
	FileOs         uint32
	FileType       uint32
	FileSubType    uint32
	FileDateMS     uint32
	FileDateLS     uint32
}

FixedFileInfo contains a "fixed" part of a file information (without any strings).

Ref VS_FIXEDFILEINFO: https://docs.microsoft.com/en-us/windows/win32/api/verrsrc/ns-verrsrc-vs_fixedfileinfo

type Info

type Info struct {
	Locales []Locale
	// contains filtered or unexported fields
}

Info contains a transparent windows object, which is being used for getting file version resource properties.

Locales is a list of locales defined for the object. For the Info created using New it's queried from `\VarFileInfo\Translation`, for ones created using NewWithLocale it's just the given locale.

A translation for the any property value is automatically chosen from Locales and then from fileversion.DefaultLocales prior to to the list order. Use GetPropertyWithLocale for deterministic selection of the property translation.

func New

func New(path string) (Info, error)

New creates an Info instance.

It queries a list of translations from the version-information resource and uses them as preferred translations for string properties.

func NewWithLocale

func NewWithLocale(path string, locale Locale) (Info, error)

NewWithLocale creates an Info instance with a given locale. All the string properties translations will be firstly queried with the given locale.

See GetPropertyWithLocale for exact properties querying.

func (Info) Comments

func (f Info) Comments() string

Comments returns Comments property.

func (Info) CompanyName

func (f Info) CompanyName() string

CompanyName returns CompanyName property.

func (Info) FileDescription

func (f Info) FileDescription() string

FileDescription returns FileDescription property.

func (Info) FileVersion

func (f Info) FileVersion() string

FileVersion returns FileVersion property.

func (Info) FixedInfo

func (f Info) FixedInfo() FixedFileInfo

FixedInfo returns a fixed (non-string) part of the file version-information resource. Contains file and product versions.

Ref: https://helloacm.com/c-function-to-get-file-version-using-win32-api-ansi-and-unicode-version/

func (Info) GetProperty

func (f Info) GetProperty(propertyName string) (string, error)

GetProperty queries a string-property from version-information resource.

Single property in a version-information resource can have multiple translations. GetProperty does its best trying to find an existing translation: it returns a first existing translation for any of .Locales and if failed tries to query it for locales from fileversion.DefaultLocales.

func (Info) GetPropertyWithLocale

func (f Info) GetPropertyWithLocale(propertyName string, locale Locale) (string, error)

GetPropertyWithLocale returns string-property with user-defined locale. It's the only way to get the property with the selected translation, all other methods do heuristics in translation choosing.

See Locale, LangID and CharsetID docs for more info about locales.

func (Info) InternalName

func (f Info) InternalName() string

InternalName returns InternalName property.

func (Info) LegalCopyright

func (f Info) LegalCopyright() string

LegalCopyright returns LegalCopyright property.

func (Info) LegalTrademarks

func (f Info) LegalTrademarks() string

LegalTrademarks returns LegalTrademarks property.

func (Info) OriginalFilename

func (f Info) OriginalFilename() string

OriginalFilename returns OriginalFilename property.

func (Info) PrivateBuild

func (f Info) PrivateBuild() string

PrivateBuild returns PrivateBuild property.

func (Info) ProductName

func (f Info) ProductName() string

ProductName returns ProductName property.

func (Info) ProductVersion

func (f Info) ProductVersion() string

ProductVersion returns ProductVersion property.

func (Info) SpecialBuild

func (f Info) SpecialBuild() string

SpecialBuild returns SpecialBuild property.

type LangID

type LangID uint16

LangID is a Windows language identifier. Could be one of the codes listed in `langID` section of https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource

type Locale

type Locale struct {
	LangID    LangID
	CharsetID CharsetID
}

Locale defines a pair of a language ID and a charsetID. It can be either any combination of predefined LangID and CharsetID or crafted manually suing values from https://docs.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource