類別 Win32::Registry

屬性

disposition[R]

配置值 (REG_CREATED_NEW_KEY 或 REG_OPENED_EXISTING_KEY)。

hkey[R]

傳回金鑰控制代值。

keyname[R]

與 Registry.open 或 Registry.create 方法的子金鑰值相同。

parent[R]

父金鑰的 Win32::Registry 物件，或如果為預先定義的金鑰，則為 nil。

公開類別方法

create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |obj| ... } 按一下以切換來源

— Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)

— Registry.create(key, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED) { |reg| … }

在 key 下建立或開啟子金鑰 subkey。您可以使用預先定義的金鑰 HKEY_* (請參閱 Constants)

如果 subkey 已存在，則會開啟 key，而 Registry#created? 方法會傳回 false。

如果提供區塊，則會自動關閉金鑰。

# File ext/win32/lib/win32/registry.rb, line 457
def self.create(hkey, subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED)
  newkey, disp = API.CreateKey(hkey.hkey, subkey, opt, desired)
  obj = new(newkey, hkey, subkey, disp)
  if block_given?
    begin
      yield obj
    ensure
      obj.close
    end
  else
    obj
  end
end

expand_environ(str) 按一下以切換來源

將 %w+% 取代為 % 之間所包含的環境值。此方法用於 REG_EXPAND_SZ。

有關詳細資訊，請參閱 expandEnvironmentStrings Win32 API。

# File ext/win32/lib/win32/registry.rb, line 373
def self.expand_environ(str)
  str.gsub(Regexp.compile("%([^%]+)%".encode(str.encoding))) {
    v = $1.encode(LOCALE)
    (e = ENV[v] || ENV[v.upcase]; e.encode(str.encoding) if e) ||
    $&
  }
end

new(hkey, parent, keyname, disposition) 按一下以切換來源

初始化

# File ext/win32/lib/win32/registry.rb, line 479
def initialize(hkey, parent, keyname, disposition)
  @hkey = hkey
  @parent = parent
  @keyname = keyname
  @disposition = disposition
  @hkeyfinal = [ hkey ]
  ObjectSpace.define_finalizer self, @@final.call(@hkeyfinal)
end

open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |obj| ... } 按一下以切換來源

— Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)

— Registry.open(key, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED) { |reg| … }

開啟 key 下的登錄機碼 subkey。key 是父機碼的 Win32::Registry 物件。您可以使用預先定義的機碼 HKEY_*（請參閱 Constants），desired 和 opt 是存取遮罩和機碼選項。有關詳細資訊，請參閱 MSDN。如果給定區塊，則會自動關閉機碼。

# File ext/win32/lib/win32/registry.rb, line 429
def self.open(hkey, subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED)
  subkey = subkey.chomp('\\')
  newkey = API.OpenKey(hkey.hkey, subkey, opt, desired)
  obj = new(newkey, hkey, subkey, REG_OPENED_EXISTING_KEY)
  if block_given?
    begin
      yield obj
    ensure
      obj.close
    end
  else
    obj
  end
end

time2wtime(time) 按一下以切換來源

將 Time 物件或 Integer 物件轉換為 64 位元 FILETIME。

# File ext/win32/lib/win32/registry.rb, line 409
def self.time2wtime(time)
  time.to_i * 10000000 + 116444736000000000
end

type2name(type) 按一下以切換來源

將登錄機碼類型值轉換為可讀取的字串。

# File ext/win32/lib/win32/registry.rb, line 395
def self.type2name(type)
  @@type2name[type] || type.to_s
end

wtime2time(wtime) 按一下以切換來源

將 64 位元 FILETIME 整數轉換為 Time 物件。

# File ext/win32/lib/win32/registry.rb, line 402
def self.wtime2time(wtime)
  Time.at((wtime - 116444736000000000) / 10000000)
end

公開執行個體方法

[](name, *rtype) 按一下以切換來源

讀取名稱為 name 的登錄機碼值，並傳回其值資料。值的類別與 read 方法傳回的值相同。

如果值類型是 REG_EXPAND_SZ，則傳回其環境變數已取代的值資料。如果值類型既不是 REG_SZ、REG_MULTI_SZ、REG_DWORD、REG_DWORD_BIG_ENDIAN，也不是 REG_QWORD，則會引發 TypeError。

rtype 的意義與 read 方法相同。

# File ext/win32/lib/win32/registry.rb, line 679
def [](name, *rtype)
  type, data = read(name, *rtype)
  case type
  when REG_SZ, REG_DWORD, REG_QWORD, REG_MULTI_SZ
    data
  when REG_EXPAND_SZ
    Registry.expand_environ(data)
  else
    raise TypeError, "Type #{Registry.type2name(type)} is not supported."
  end
end

[]=(name, rtype, value = nil) 按一下以切換來源

將值寫入名稱為 name 的登錄機碼值。

如果指定 wtype，則值類型為它。否則，值類型取決於值類別：:Integer

REG_DWORD

:String

REG_SZ

:Array

REG_MULTI_SZ

# File ext/win32/lib/win32/registry.rb, line 774
def []=(name, rtype, value = nil)
  if value
    write name, rtype, value
  else
    case value = rtype
    when Integer
      write name, REG_DWORD, value
    when String
      write name, REG_SZ, value
    when Array
      write name, REG_MULTI_SZ, value
    else
      raise TypeError, "Unexpected type #{value.class}"
    end
  end
  value
end

_dump(depth) 按一下以切換來源

不允許封送

# File ext/win32/lib/win32/registry.rb, line 534
def _dump(depth)
  raise TypeError, "can't dump Win32::Registry"
end

close() 按一下以切換來源

關閉機碼。

關閉後，大多數方法會引發錯誤。

# File ext/win32/lib/win32/registry.rb, line 557
def close
  API.CloseKey(@hkey)
  @hkey = @parent = @keyname = nil
  @hkeyfinal[0] = nil
end

create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk) 按一下以切換來源

與 Win32::Registry.create (self, subkey, desired, opt) 相同

# File ext/win32/lib/win32/registry.rb, line 548
def create(subkey, desired = KEY_ALL_ACCESS, opt = REG_OPTION_RESERVED, &blk)
  self.class.create(self, subkey, desired, opt, &blk)
end

created?() 按一下以切換來源

傳回是否已建立金鑰（新的）。（請參閱 Registry.create）– 基本上，您會呼叫 create，然後在呼叫已傳回執行個體的 created? 時，它會告知是否成功

# File ext/win32/lib/win32/registry.rb, line 504
def created?
  @disposition == REG_CREATED_NEW_KEY
end

delete(name)

別名：delete_value

delete_key(name, recursive = false) 按一下以切換來源

刪除名為 name 的子金鑰及其所有值。

如果 recursive 為 false，則子金鑰不得具有子金鑰。否則，此方法會遞迴刪除所有子金鑰和值。

# File ext/win32/lib/win32/registry.rb, line 837
def delete_key(name, recursive = false)
  if recursive
    open(name, KEY_ALL_ACCESS) do |reg|
      reg.keys.each do |key|
        begin
          reg.delete_key(key, true)
        rescue Error
          #
        end
      end
    end
    API.DeleteKey(@hkey, name)
  else
    begin
      API.EnumKey @hkey, 0
    rescue Error
      return API.DeleteKey(@hkey, name)
    end
    raise Error.new(5) ## ERROR_ACCESS_DENIED
  end
end

delete_value(name) 按一下以切換來源

刪除名為 name 的登錄值。我們無法刪除「預設」值。

# File ext/win32/lib/win32/registry.rb, line 826
def delete_value(name)
  API.DeleteValue(@hkey, name)
end

別名：delete

each()

別名：each_value

each_key() { |subkey, wtime| ... } 按一下以切換來源

列舉子金鑰。

subkey 是 String，其中包含子金鑰的名稱。wtime 是最後寫入時間，表示為 FILETIME（64 位元整數）。（請參閱 Registry.wtime2time）

# File ext/win32/lib/win32/registry.rb, line 603
def each_key
  index = 0
  while true
    begin
      subkey, wtime = API.EnumKey(@hkey, index)
    rescue Error
      break
    end
    subkey = export_string(subkey)
    yield subkey, wtime
    index += 1
  end
  index
end

each_value() { |subkey, type, data| ... } 按一下以切換來源

列舉值。

# File ext/win32/lib/win32/registry.rb, line 566
def each_value
  index = 0
  while true
    begin
      subkey = API.EnumValue(@hkey, index)
    rescue Error
      break
    end
    subkey = export_string(subkey)
    begin
      type, data = read(subkey)
    rescue Error
    else
      yield subkey, type, data
    end
    index += 1
  end
  index
end

別名：each

flush() 按一下以切換來源

將所有屬性寫入登錄檔檔案。

# File ext/win32/lib/win32/registry.rb, line 862
def flush
  API.FlushKey @hkey
end

info() 按一下以切換來源

傳回金鑰資訊，表示為 Array 的：:num_keys

The number of subkeys.

:max_key_length

Maximum length of name of subkeys.

:num_values

The number of values.

:max_value_name_length

Maximum length of name of values.

:max_value_length

Maximum length of value of values.

:descriptor_length

Length of security descriptor.

:wtime

Last write time as FILETIME(64-bit integer)

詳細資訊請參閱 RegQueryInfoKey Win32 API。

# File ext/win32/lib/win32/registry.rb, line 885
def info
  API.QueryInfoKey(@hkey)
end

inspect() 按一下以切換來源

# File ext/win32/lib/win32/registry.rb, line 527
def inspect
  "\#<Win32::Registry key=#{name.inspect}>"
end

keys() 按一下以切換來源

將金鑰傳回為陣列

# File ext/win32/lib/win32/registry.rb, line 621
def keys
  keys_ary = []
  each_key { |key,| keys_ary << key }
  keys_ary
end

name() 按一下以切換來源

金鑰的完整路徑，例如 ‘HKEY_CURRENT_USERSOFTWAREfoobar’。

# File ext/win32/lib/win32/registry.rb, line 518
def name
  parent = self
  name = @keyname
  while parent = parent.parent
    name = parent.keyname + '\\' + name
  end
  name
end

open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk) 按一下以切換來源

與 Win32::Registry.open (self, subkey, desired, opt) 相同

# File ext/win32/lib/win32/registry.rb, line 541
def open(subkey, desired = KEY_READ, opt = REG_OPTION_RESERVED, &blk)
  self.class.open(self, subkey, desired, opt, &blk)
end

open?() 按一下以切換來源

傳回金鑰是否未關閉。

# File ext/win32/lib/win32/registry.rb, line 511
def open?
  !@hkey.nil?
end

read(name, *rtype) 按一下以切換來源

讀取名為 name 的登錄機碼值，並傳回 [ 類型、資料 ] 陣列。當 name 為 nil 時，會讀取 ‘預設’ 值。類型是值類型。(請參閱 Win32::Registry::Constants 模組) 資料是值資料，其類別為：:REG_SZ、REG_EXPAND_SZ

String

:REG_MULTI_SZ

Array of String

:REG_DWORD、REG_DWORD_BIG_ENDIAN、REG_QWORD

Integer

:REG_BINARY、REG_NONE

String (contains binary data)

當指定 rtype 時，值類型必須包含在 rtype 陣列中，否則會引發 TypeError。

# File ext/win32/lib/win32/registry.rb, line 643
def read(name, *rtype)
  type, data = API.QueryValue(@hkey, name)
  unless rtype.empty? or rtype.include?(type)
    raise TypeError, "Type mismatch (expect [#{
      rtype.map{|t|Registry.type2name(t)}.join(', ')}] but #{
      Registry.type2name(type)} present)"
  end
  case type
  when REG_SZ, REG_EXPAND_SZ
    [ type, data.encode(name.encoding, WCHAR).chop ]
  when REG_MULTI_SZ
    [ type, data.encode(name.encoding, WCHAR).split(/\0/) ]
  when REG_BINARY, REG_NONE
    [ type, data ]
  when REG_DWORD
    [ type, API.unpackdw(data) ]
  when REG_DWORD_BIG_ENDIAN
    [ type, data.unpack('N')[0] ]
  when REG_QWORD
    [ type, API.unpackqw(data) ]
  else
    raise TypeError, "Type #{Registry.type2name(type)} is not supported."
  end
end

read_bin(name) 按一下以切換來源

讀取名為 name 的 REG_SZ(read_s)、REG_DWORD(read_i) 或 REG_BINARY(read_bin) 登錄機碼值。

如果值類型不符，會引發 TypeError。

# File ext/win32/lib/win32/registry.rb, line 730
def read_bin(name)
  read(name, REG_BINARY)[1]
end

read_i(name) 按一下以切換來源

讀取名為 name 的 REG_SZ(read_s)、REG_DWORD(read_i) 或 REG_BINARY(read_bin) 登錄機碼值。

如果值類型不符，會引發 TypeError。

# File ext/win32/lib/win32/registry.rb, line 720
def read_i(name)
  read(name, REG_DWORD, REG_DWORD_BIG_ENDIAN, REG_QWORD)[1]
end

read_s(name) 按一下以切換來源

讀取名為 name 的 REG_SZ(read_s)、REG_DWORD(read_i) 或 REG_BINARY(read_bin) 登錄機碼值。

如果值類型不符，會引發 TypeError。

# File ext/win32/lib/win32/registry.rb, line 695
def read_s(name)
  read(name, REG_SZ)[1]
end

read_s_expand(name) 按一下以切換來源

讀取名為 name 的 REG_SZ 或 REG_EXPAND_SZ 登錄機碼值。

如果值類型為 REG_EXPAND_SZ，會取代環境變數。除非值類型為 REG_SZ 或 REG_EXPAND_SZ，否則會引發 TypeError。

# File ext/win32/lib/win32/registry.rb, line 705
def read_s_expand(name)
  type, data = read(name, REG_SZ, REG_EXPAND_SZ)
  if type == REG_EXPAND_SZ
    Registry.expand_environ(data)
  else
    data
  end
end

values() 按一下以切換來源

回傳值為陣列

# File ext/win32/lib/win32/registry.rb, line 590
def values
  vals_ary = []
  each_value { |*, val| vals_ary << val }
  vals_ary
end

write(name, type, data) 按一下以切換來源

將資料寫入名稱為 name 的登錄值。當 name 為 nil 時，寫入「預設」值。

type 為類型值。（請參閱 Registry::Constants 模組）資料的 類別 必須與 read 方法回傳的類別相同。

# File ext/win32/lib/win32/registry.rb, line 742
def write(name, type, data)
  case type
  when REG_SZ, REG_EXPAND_SZ
    data = data.encode(WCHAR) << WCHAR_NUL
  when REG_MULTI_SZ
    data = data.to_a.map {|s| s.encode(WCHAR)}.join(WCHAR_NUL) << WCHAR_NUL
  when REG_BINARY, REG_NONE
    data = data.to_s
  when REG_DWORD
    data = API.packdw(data.to_i)
  when REG_DWORD_BIG_ENDIAN
    data = [data.to_i].pack('N')
  when REG_QWORD
    data = API.packqw(data.to_i)
  else
    raise TypeError, "Unsupported type #{Registry.type2name(type)}"
  end
  API.SetValue(@hkey, name, type, data, data.bytesize)
end

write_bin(name, value) 按一下以切換來源

將值寫入名稱為 name 的登錄機碼值。

值類型為 REG_SZ(write_s)、REG_DWORD(write_i) 或 REG_BINARY(write_bin)。

# File ext/win32/lib/win32/registry.rb, line 818
def write_bin(name, value)
  write name, REG_BINARY, value.to_s
end

write_i(name, value) 按一下以切換來源

將值寫入名稱為 name 的登錄機碼值。

值類型為 REG_SZ(write_s)、REG_DWORD(write_i) 或 REG_BINARY(write_bin)。

# File ext/win32/lib/win32/registry.rb, line 808
def write_i(name, value)
  write name, REG_DWORD, value.to_i
end

write_s(name, value) 按一下以切換來源

將值寫入名稱為 name 的登錄機碼值。

值類型為 REG_SZ(write_s)、REG_DWORD(write_i) 或 REG_BINARY(write_bin)。

# File ext/win32/lib/win32/registry.rb, line 798
def write_s(name, value)
  write name, REG_SZ, value.to_s
end