Module: Libvirt
- Defined in:
- lib/libvirt.rb,
ext/libvirt/_libvirt.c
Defined Under Namespace
Classes: ConnectionError, DefinitionError, Error, Interface, NWFilter, NoSupportError, NodeDevice, RetrieveError, Version
Constant Summary collapse
- CONNECT_RO =
INT2NUM(VIR_CONNECT_RO)
- CRED_USERNAME =
INT2NUM(VIR_CRED_USERNAME)
- CRED_AUTHNAME =
INT2NUM(VIR_CRED_AUTHNAME)
- CRED_LANGUAGE =
INT2NUM(VIR_CRED_LANGUAGE)
- CRED_CNONCE =
INT2NUM(VIR_CRED_CNONCE)
- CRED_PASSPHRASE =
INT2NUM(VIR_CRED_PASSPHRASE)
- CRED_ECHOPROMPT =
INT2NUM(VIR_CRED_ECHOPROMPT)
- CRED_NOECHOPROMPT =
INT2NUM(VIR_CRED_NOECHOPROMPT)
- CRED_REALM =
INT2NUM(VIR_CRED_REALM)
- CRED_EXTERNAL =
INT2NUM(VIR_CRED_EXTERNAL)
- CONNECT_NO_ALIASES =
INT2NUM(VIR_CONNECT_NO_ALIASES)
- EVENT_HANDLE_READABLE =
INT2NUM(VIR_EVENT_HANDLE_READABLE)
- EVENT_HANDLE_WRITABLE =
INT2NUM(VIR_EVENT_HANDLE_WRITABLE)
- EVENT_HANDLE_ERROR =
INT2NUM(VIR_EVENT_HANDLE_ERROR)
- EVENT_HANDLE_HANGUP =
INT2NUM(VIR_EVENT_HANDLE_HANGUP)
Class Method Summary collapse
-
.Libvirt::event_invoke_handle_callback(handle, fd, events, opaque) ⇒ Qnil
Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function.
-
.Libvirt::event_invoke_timeout_callback(timer, opaque) ⇒ Qnil
Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function.
-
.Libvirt::event_register_impl(add_handle = nil, update_handle = nil, remove_handle = nil, add_timeout = nil, update_timeout = nil, remove_timeout = nil) ⇒ Qnil
Call virEventRegisterImpl to register callback handlers for handles and timeouts.
-
.Libvirt::open(uri = nil) ⇒ Libvirt::Connect
Call virConnectOpen to open a connection to a URL.
-
.Libvirt::open_auth(uri = nil, credlist = nil, userdata = nil, flags = 0) {|...| ... } ⇒ Libvirt::Connect
Call virConnectOpenAuth to open a connection to a libvirt URI, with a possible authentication block.
-
.Libvirt::open_read_only(uri = nil) ⇒ Libvirt::Connect
Call virConnectOpenReadOnly to open a read-only connection to a URL.
-
.Libvirt::version(type = nil) ⇒ Array
Call virGetVersion to get the version of libvirt and of the hypervisor TYPE.
Instance Method Summary collapse
-
#Libvirt::lxc_enter_security_label(model, label, flags = 0) ⇒ Libvirt::Domain::SecurityLabel
Call virDomainLxcEnterSecurityLabel to attach to the security label specified by label in the security model specified by model.
Class Method Details
.Libvirt::event_invoke_handle_callback(handle, fd, events, opaque) ⇒ Qnil
Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function. Instead, this module method (and event_invoke_timeout_callback) are meant to be called when there is an event of interest to libvirt on one of the file descriptors that libvirt uses. The application is notified of the file descriptors that libvirt uses via the callbacks from Libvirt::event_register_impl. When there is an event of interest, the application must call event_invoke_timeout_callback to ensure proper operation.
Libvirt::event_invoke_handle_callback takes 4 arguments:
handle - an application specific handle ID. This can be any integer, but must be unique from all other libvirt handles in the application.
fd - the file descriptor of interest. This was given to the application as a callback to add_handle of Libvirt::event_register_impl
events - the events that have occured on the fd. Note that the events are libvirt specific, and are some combination of Libvirt::EVENT_HANDLE_READABLE, Libvirt::EVENT_HANDLE_WRITABLE, Libvirt::EVENT_HANDLE_ERROR, Libvirt::EVENT_HANDLE_HANGUP. To notify libvirt of more than one event at a time, these values should be logically OR’ed together.
opaque - the opaque data passed from libvirt during the Libvirt::event_register_impl add_handle callback. To ensure proper operation this data must be passed through to event_invoke_handle_callback without modification.
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 |
# File 'ext/libvirt/_libvirt.c', line 294
static VALUE libvirt_event_invoke_handle_callback(VALUE RUBY_LIBVIRT_UNUSED(m),
VALUE handle, VALUE fd,
VALUE events, VALUE opaque)
{
virEventHandleCallback cb;
void *op;
VALUE libvirt_cb, libvirt_opaque;
Check_Type(opaque, T_HASH);
libvirt_cb = rb_hash_aref(opaque, rb_str_new2("libvirt_cb"));
/* This is equivalent to Data_Get_Struct; I reproduce it here because
* I don't want the additional type-cast that Data_Get_Struct does
*/
Check_Type(libvirt_cb, T_DATA);
cb = DATA_PTR(libvirt_cb);
if (cb) {
libvirt_opaque = rb_hash_aref(opaque, rb_str_new2("opaque"));
Data_Get_Struct(libvirt_opaque, void *, op);
cb(NUM2INT(handle), NUM2INT(fd), NUM2INT(events), op);
}
return Qnil;
}
|
.Libvirt::event_invoke_timeout_callback(timer, opaque) ⇒ Qnil
Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function. Instead, this module method (and event_invoke_handle_callback) are meant to be called when there is a timeout of interest to libvirt. The application is notified of the timers that libvirt uses via the callbacks from Libvirt::event_register_impl. When a timeout expires, the application must call event_invoke_timeout_callback to ensure proper operation.
Libvirt::event_invoke_timeout_callback takes 2 arguments:
handle - an application specific timer ID. This can be any integer, but must be unique from all other libvirt timers in the application.
opaque - the opaque data passed from libvirt during the Libvirt::event_register_impl add_handle callback. To ensure proper operation this data must be passed through to event_invoke_handle_callback without modification.
339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 |
# File 'ext/libvirt/_libvirt.c', line 339
static VALUE libvirt_event_invoke_timeout_callback(VALUE RUBY_LIBVIRT_UNUSED(m),
VALUE timer, VALUE opaque)
{
virEventTimeoutCallback cb;
void *op;
VALUE libvirt_cb, libvirt_opaque;
Check_Type(opaque, T_HASH);
libvirt_cb = rb_hash_aref(opaque, rb_str_new2("libvirt_cb"));
/* This is equivalent to Data_Get_Struct; I reproduce it here because
* I don't want the additional type-cast that Data_Get_Struct does
*/
Check_Type(libvirt_cb, T_DATA);
cb = DATA_PTR(libvirt_cb);
if (cb) {
libvirt_opaque = rb_hash_aref(opaque, rb_str_new2("opaque"));
Data_Get_Struct(libvirt_opaque, void *, op);
cb(NUM2INT(timer), op);
}
return Qnil;
}
|
.Libvirt::event_register_impl(add_handle = nil, update_handle = nil, remove_handle = nil, add_timeout = nil, update_timeout = nil, remove_timeout = nil) ⇒ Qnil
Call virEventRegisterImpl to register callback handlers for handles and timeouts. These handles and timeouts are used as part of the libvirt infrastructure for generating domain events. Each callback must be a Symbol (that is the name of a method to callback), a Proc, or nil (to disable the callback). In the end-user application program, these callbacks are typically used to track the file descriptors or timers that libvirt is interested in (and is intended to be integrated into the “main loop” of a UI program). The individual callbacks will be given a certain number of arguments, and must return certain values. Those arguments and return types are:
add_handle(fd, events, opaque) => Fixnum
update_handle(handleID, event) => nil
remove_handle(handleID) => opaque data from add_handle
add_timeout(interval, opaque) => Fixnum
update_timeout(timerID, timeout) => nil
remove_timeout(timerID) => opaque data from add_timeout
Any arguments marked as “opaque” must be accepted from the library and saved without modification. The values passed to the callbacks are meant to be passed to the event_invoke_handle_callback and event_invoke_timeout_callback module methods; see the documentation for those methods for more details.
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 |
# File 'ext/libvirt/_libvirt.c', line 606
static VALUE libvirt_conn_event_register_impl(int argc, VALUE *argv,
VALUE RUBY_LIBVIRT_UNUSED(c))
{
virEventAddHandleFunc add_handle_temp;
virEventUpdateHandleFunc update_handle_temp;
virEventRemoveHandleFunc remove_handle_temp;
virEventAddTimeoutFunc add_timeout_temp;
virEventUpdateTimeoutFunc update_timeout_temp;
virEventRemoveTimeoutFunc remove_timeout_temp;
/*
* subtle; we put the arguments (callbacks) directly into the global
* add_handle, update_handle, etc. variables. Then we register the
* internal functions as the callbacks with virEventRegisterImpl
*/
rb_scan_args(argc, argv, "06", &add_handle, &update_handle, &remove_handle,
&add_timeout, &update_timeout, &remove_timeout);
if (!is_symbol_proc_or_nil(add_handle) ||
!is_symbol_proc_or_nil(update_handle) ||
!is_symbol_proc_or_nil(remove_handle) ||
!is_symbol_proc_or_nil(add_timeout) ||
!is_symbol_proc_or_nil(update_timeout) ||
!is_symbol_proc_or_nil(remove_timeout)) {
rb_raise(rb_eTypeError,
"wrong argument type (expected Symbol, Proc, or nil)");
}
set_event_func_or_null(add_handle);
set_event_func_or_null(update_handle);
set_event_func_or_null(remove_handle);
set_event_func_or_null(add_timeout);
set_event_func_or_null(update_timeout);
set_event_func_or_null(remove_timeout);
/* virEventRegisterImpl returns void, so no error checking here */
virEventRegisterImpl(add_handle_temp, update_handle_temp,
remove_handle_temp, add_timeout_temp,
update_timeout_temp, remove_timeout_temp);
return Qnil;
}
|
.Libvirt::open(uri = nil) ⇒ Libvirt::Connect
Call virConnectOpen to open a connection to a URL.
96 97 98 99 100 101 102 103 104 105 106 107 108 |
# File 'ext/libvirt/_libvirt.c', line 96
static VALUE libvirt_open(int argc, VALUE *argv, VALUE RUBY_LIBVIRT_UNUSED(m))
{
VALUE uri;
virConnectPtr conn;
rb_scan_args(argc, argv, "01", &uri);
conn = virConnectOpen(ruby_libvirt_get_cstring_or_null(uri));
ruby_libvirt_raise_error_if(conn == NULL, e_ConnectionError,
"virConnectOpen", NULL);
return ruby_libvirt_connect_new(conn);
}
|
.Libvirt::open_auth(uri = nil, credlist = nil, userdata = nil, flags = 0) {|...| ... } ⇒ Libvirt::Connect
Call virConnectOpenAuth to open a connection to a libvirt URI, with a possible authentication block. If an authentication block is desired, then credlist should be an array that specifies which credentials the authentication block is willing to support; the full list is available at libvirt.org/html/libvirt-libvirt.html#virConnectCredentialType. If userdata is not nil and an authentication block is given, userdata will be passed unaltered into the authentication block. The flags parameter controls how to open connection. The only options currently available for flags are 0 for a read/write connection and Libvirt::CONNECT_RO for a read-only connection.
If the credlist is not empty, and an authentication block is given, the authentication block will be called once for each credential necessary to complete the authentication. The authentication block will be passed a single parameter, which is a hash of values containing information necessary to complete authentication. This hash contains 5 elements:
type - the type of credential to be examined
prompt - a suggested prompt to show to the user
challenge - any additional challenge information
defresult - a default result to use if credentials could not be obtained
userdata - the userdata passed into open_auth initially
The authentication block should return the result of collecting the information; these results will then be sent to libvirt for authentication.
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 |
# File 'ext/libvirt/_libvirt.c', line 217
static VALUE libvirt_open_auth(int argc, VALUE *argv,
VALUE RUBY_LIBVIRT_UNUSED(m))
{
virConnectAuthPtr auth;
VALUE uri, credlist, userdata, flags, tmp;
virConnectPtr conn;
unsigned int i;
rb_scan_args(argc, argv, "04", &uri, &credlist, &userdata, &flags);
if (rb_block_given_p()) {
auth = alloca(sizeof(virConnectAuth));
if (TYPE(credlist) == T_NIL) {
auth->ncredtype = 0;
}
else if (TYPE(credlist) == T_ARRAY) {
auth->ncredtype = RARRAY_LEN(credlist);
}
else {
rb_raise(rb_eTypeError,
"wrong argument type (expected Array or nil)");
}
auth->credtype = NULL;
if (auth->ncredtype > 0) {
auth->credtype = alloca(sizeof(int) * auth->ncredtype);
for (i = 0; i < auth->ncredtype; i++) {
tmp = rb_ary_entry(credlist, i);
auth->credtype[i] = NUM2INT(tmp);
}
}
auth->cb = libvirt_auth_callback_wrapper;
auth->cbdata = (void *)userdata;
}
else {
auth = virConnectAuthPtrDefault;
}
conn = virConnectOpenAuth(ruby_libvirt_get_cstring_or_null(uri), auth,
ruby_libvirt_value_to_uint(flags));
ruby_libvirt_raise_error_if(conn == NULL, e_ConnectionError,
"virConnectOpenAuth", NULL);
return ruby_libvirt_connect_new(conn);
}
|
.Libvirt::open_read_only(uri = nil) ⇒ Libvirt::Connect
Call virConnectOpenReadOnly to open a read-only connection to a URL.
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 |
# File 'ext/libvirt/_libvirt.c', line 117
static VALUE libvirt_open_read_only(int argc, VALUE *argv,
VALUE RUBY_LIBVIRT_UNUSED(m))
{
VALUE uri;
virConnectPtr conn;
rb_scan_args(argc, argv, "01", &uri);
conn = virConnectOpenReadOnly(ruby_libvirt_get_cstring_or_null(uri));
ruby_libvirt_raise_error_if(conn == NULL, e_ConnectionError,
"virConnectOpenReadOnly", NULL);
return ruby_libvirt_connect_new(conn);
}
|
.Libvirt::version(type = nil) ⇒ Array
Call virGetVersion to get the version of libvirt and of the hypervisor TYPE.
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 |
# File 'ext/libvirt/_libvirt.c', line 66
static VALUE libvirt_version(int argc, VALUE *argv,
VALUE RUBY_LIBVIRT_UNUSED(m))
{
unsigned long libVer, typeVer;
VALUE type, result, rargv[2];
int r;
rb_scan_args(argc, argv, "01", &type);
r = virGetVersion(&libVer, ruby_libvirt_get_cstring_or_null(type),
&typeVer);
ruby_libvirt_raise_error_if(r < 0, rb_eArgError, "virGetVersion", NULL);
result = rb_ary_new2(2);
rargv[0] = rb_str_new2("libvirt");
rargv[1] = ULONG2NUM(libVer);
rb_ary_store(result, 0, rb_class_new_instance(2, rargv, c_libvirt_version));
rargv[0] = type;
rargv[1] = ULONG2NUM(typeVer);
rb_ary_store(result, 1, rb_class_new_instance(2, rargv, c_libvirt_version));
return result;
}
|
Instance Method Details
#Libvirt::lxc_enter_security_label(model, label, flags = 0) ⇒ Libvirt::Domain::SecurityLabel
Call virDomainLxcEnterSecurityLabel to attach to the security label specified by label in the security model specified by model. The return object is a Libvirt::Domain::SecurityLabel which may be able to be used to move back to the previous label.
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 |
# File 'ext/libvirt/_libvirt.c', line 660
static VALUE libvirt_domain_lxc_enter_security_label(int argc, VALUE *argv,
VALUE RUBY_LIBVIRT_UNUSED(c))
{
VALUE model, label, flags, result, modiv, doiiv, labiv;
virSecurityModel mod;
char *modstr, *doistr, *labstr;
virSecurityLabel lab, oldlab;
int ret;
rb_scan_args(argc, argv, "21", &model, &label, &flags);
if (rb_class_of(model) != c_node_security_model) {
rb_raise(rb_eTypeError,
"wrong argument type (expected Libvirt::Connect::NodeSecurityModel)");
}
if (rb_class_of(label) != c_domain_security_label) {
rb_raise(rb_eTypeError,
"wrong argument type (expected Libvirt::Domain::SecurityLabel)");
}
modiv = rb_iv_get(model, "@model");
modstr = StringValueCStr(modiv);
memcpy(mod.model, modstr, strlen(modstr));
doiiv = rb_iv_get(model, "@doi");
doistr = StringValueCStr(doiiv);
memcpy(mod.doi, doistr, strlen(doistr));
labiv = rb_iv_get(label, "@label");
labstr = StringValueCStr(labiv);
memcpy(lab.label, labstr, strlen(labstr));
lab.enforcing = NUM2INT(rb_iv_get(label, "@enforcing"));
ret = virDomainLxcEnterSecurityLabel(&mod, &lab, &oldlab,
ruby_libvirt_value_to_uint(flags));
ruby_libvirt_raise_error_if(ret < 0, e_RetrieveError,
"virDomainLxcEnterSecurityLabel", NULL);
result = rb_class_new_instance(0, NULL, c_domain_security_label);
rb_iv_set(result, "@label", rb_str_new2(oldlab.label));
rb_iv_set(result, "@enforcing", INT2NUM(oldlab.enforcing));
return result;
}
|