winevt_c 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f9385269dcef7feb299a038947855285d7ffb76d8d331941dfa2d30f56fdb4
-  data.tar.gz: f122b6172ae73587a3a518d79d25a7a64daa735a552fb998cfd5f9e2a5fddc07
+  metadata.gz: b390dc340de45facd91c7de698c1d72f7f706e961f6beb776a748499886fa4c2
+  data.tar.gz: cb6bb22241cb81551cbb84363e7c9bddb205f38fb6aa138da2c6c4489667044c
 SHA512:
-  metadata.gz: 92d91fafb48fe5a4cc63ad82a9eca050cac7e2db38538347f6a9c247b5218604360a155233d1f37c38ce9967ca6af46f150fedb0d77c261e201fb99a675c0996
-  data.tar.gz: 5fcc3b81d00788d63380692942fe29822fe6a53d058463ce7848409310abb242a187dfb24414c5cdfc17943d6b57f027a9e1ddbeb2ae03c7eee2594215080eb1
+  metadata.gz: b8e2666c0d51dcf9bfc114c1bd73b1f075a1702999d44e8dd318878d837b762a568aceffffadfc89f0ce33010629fb677f0edd040a312d32a5f35a20c6f3f0cc
+  data.tar.gz: 6adec333c1e0998a712b149f470091ed24f441806b5454a05e80d937bca63de7346b806ddd1904835428344158e81108b12a1cc2aa628a595299ed243ce83abc

data/README.md

@@ -24,6 +24,10 @@ Or install it yourself as:
 
     $ ridk exec gem install winevt_c
 
+## Fat gems building
+
+* Docker is needed to build fat gem due to rake-compiler-dock uses docker container.
+
 ## Usage
 
 Usage examples are found in [example directory](example).

data/Rakefile

@@ -27,7 +27,7 @@ desc 'Build gems for Windows per rake-compiler-dock'
 task 'gem:native' do
   # See RUBY_CC_VERSION in https://github.com/rake-compiler/rake-compiler-dock/blob/master/Dockerfile.mri
   RakeCompilerDock.sh <<-EOS
-    bundle --local
+    gem install bundler --no-doc && bundle --local
     bundle exec rake cross native gem RUBY_CC_VERSION=2.4.0:2.5.0:2.6.0
 EOS
 end

data/ext/winevt/winevt_bookmark.c

@@ -1,5 +1,24 @@
 #include <winevt_c.h>
 
+/* clang-format off */
+/*
+ * Document-class: Winevt::EventLog::Bookmark
+ *
+ * Bookmark for querying/subscribing Windows EventLog progress.
+ *
+ * @example
+ *  require 'winevt'
+ *
+ *  @query = Winevt::EventLog::Query.new("Application", "*[System[(Level <= 3) and TimeCreated[timediff(@SystemTime) <= 86400000]]]")
+ *  @bookmark = Winevt::EventLog::Bookmark.new
+ *  @query.each do |xml|
+ *    @bookmark.update(@query)
+ *  end
+ *
+ *  puts @bookmark.render
+ */
+/* clang-format pn */
+
 static void bookmark_free(void* ptr);
 
 static const rb_data_type_t rb_winevt_bookmark_type = { "winevt/bookmark",
@@ -32,6 +51,14 @@ rb_winevt_bookmark_alloc(VALUE klass)
   return obj;
 }
 
+/*
+ * Initalize Bookmark class. Receive XML string or nil.
+ *
+ * @overload initailize(options={})
+ *   @option options [String] XML rendered Bookmark string.
+ * @return [Bookmark]
+ *
+ */
 static VALUE
 rb_winevt_bookmark_initialize(int argc, VALUE* argv, VALUE self)
 {
@@ -68,6 +95,12 @@ rb_winevt_bookmark_initialize(int argc, VALUE* argv, VALUE self)
   return Qnil;
 }
 
+/*
+ * This method updates bookmark and returns Bookmark instance.
+ *
+ * @param event [Query]
+ * @return [Bookmark]
+ */
 static VALUE
 rb_winevt_bookmark_update(VALUE self, VALUE event)
 {
@@ -86,6 +119,11 @@ rb_winevt_bookmark_update(VALUE self, VALUE event)
   return Qtrue;
 }
 
+/*
+ * This method renders bookmark class content.
+ *
+ * @return [String]
+ */
 static VALUE
 rb_winevt_bookmark_render(VALUE self)
 {

data/ext/winevt/winevt_c.h

@@ -27,6 +27,7 @@ extern "C" {
 #endif /* __cplusplus */
 
 VALUE wstr_to_rb_str(UINT cp, const WCHAR* wstr, int clen);
+void  raise_system_error(VALUE error, DWORD errorCode);
 VALUE render_to_rb_str(EVT_HANDLE handle, DWORD flags);
 WCHAR* get_description(EVT_HANDLE handle);
 VALUE get_values(EVT_HANDLE handle);

data/ext/winevt/winevt_channel.c

@@ -1,5 +1,20 @@
 #include <winevt_c.h>
 
+/*
+ * Document-class: Winevt::EventLog::Channel
+ *
+ * Retrieve Windows EventLog channel name.
+ *
+ * @example
+ *  require 'winevt'
+ *  channels = []
+ *  @channel = Winevt::EventLog::Channel.new
+ *  @channel.each do |channel|
+ *    channels << channel
+ *  end
+ *  print channels
+ */
+
 static void channel_free(void* ptr);
 
 static const rb_data_type_t rb_winevt_channel_type = { "winevt/channel",
@@ -32,12 +47,24 @@ rb_winevt_channel_alloc(VALUE klass)
   return obj;
 }
 
+/*
+ * Initalize Channel class.
+ *
+ * @return [Channel]
+ *
+ */
 static VALUE
 rb_winevt_channel_initialize(VALUE klass)
 {
   return Qnil;
 }
 
+/*
+ * Enumerate Windows EventLog channels
+ *
+ * @yield (String)
+ *
+ */
 static VALUE
 rb_winevt_channel_each(VALUE self)
 {

data/ext/winevt/winevt_query.c

@@ -1,5 +1,23 @@
 #include <winevt_c.h>
 
+/* clang-format off */
+/*
+ * Document-class: Winevt::EventLog::Query
+ *
+ * Query Windows EventLog channel.
+ *
+ * @example
+ *  require 'winevt'
+ *
+ *  @query = Winevt::EventLog::Query.new("Application", "*[System[(Level <= 3) and TimeCreated[timediff(@SystemTime) <= 86400000]]]")
+ *
+ *  @query.each do |eventlog, message, string_inserts|
+ *    puts ({eventlog: eventlog, data: message})
+ *  end
+ */
+/* clang-format on */
+
+
 static void query_free(void* ptr);
 
 static const rb_data_type_t rb_winevt_query_type = { "winevt/query",
@@ -36,6 +54,14 @@ rb_winevt_query_alloc(VALUE klass)
   return obj;
 }
 
+/*
+ * Initalize Query class.
+ *
+ * @param channel [String] Querying EventLog channel.
+ * @param xpath [String] Querying XPath.
+ * @return [Query]
+ *
+ */
 static VALUE
 rb_winevt_query_initialize(VALUE self, VALUE channel, VALUE xpath)
 {
@@ -75,8 +101,13 @@ rb_winevt_query_initialize(VALUE self, VALUE channel, VALUE xpath)
   return Qnil;
 }
 
+/*
+ * This method returns querying event offset.
+ *
+ * @return [Integer]
+ */
 static VALUE
-rb_winevt_query_get_offset(VALUE self, VALUE offset)
+rb_winevt_query_get_offset(VALUE self)
 {
   struct WinevtQuery* winevtQuery;
 
@@ -85,6 +116,11 @@ rb_winevt_query_get_offset(VALUE self, VALUE offset)
   return LONG2NUM(winevtQuery->offset);
 }
 
+/*
+ * This method specifies querying event offset.
+ *
+ * @param offset [Integer] offset value
+ */
 static VALUE
 rb_winevt_query_set_offset(VALUE self, VALUE offset)
 {
@@ -97,8 +133,13 @@ rb_winevt_query_set_offset(VALUE self, VALUE offset)
   return Qnil;
 }
 
+/*
+ * This method returns timeout value.
+ *
+ * @return [Integer]
+ */
 static VALUE
-rb_winevt_query_get_timeout(VALUE self, VALUE timeout)
+rb_winevt_query_get_timeout(VALUE self)
 {
   struct WinevtQuery* winevtQuery;
 
@@ -107,6 +148,11 @@ rb_winevt_query_get_timeout(VALUE self, VALUE timeout)
   return LONG2NUM(winevtQuery->timeout);
 }
 
+/*
+ * This method specifies timeout value.
+ *
+ * @param timeout [Integer] timeout value
+ */
 static VALUE
 rb_winevt_query_set_timeout(VALUE self, VALUE timeout)
 {
@@ -119,6 +165,14 @@ rb_winevt_query_set_timeout(VALUE self, VALUE timeout)
   return Qnil;
 }
 
+/*
+ * Handle the next values. Since v0.6.0, this method is used for
+ * testing only. Please use #each instead.
+ *
+ * @return [Boolean]
+ *
+ * @see each
+ */
 static VALUE
 rb_winevt_query_next(VALUE self)
 {
@@ -138,7 +192,7 @@ rb_winevt_query_next(VALUE self)
 
   if (status == ERROR_SUCCESS) {
     winevtQuery->count = count;
-    for (int i = 0; i < count; i++){
+    for (int i = 0; i < count; i++) {
       winevtQuery->hEvents[i] = hEvents[i];
     }
 
@@ -202,6 +256,12 @@ get_evt_seek_flag_from_cstr(char* flag_str)
   return 0;
 }
 
+/*
+ * This method specifies seek strategy.
+ *
+ * @param bookmark_or_flag [Bookmark|Query::Flag]
+ * @return [Boolean]
+ */
 static VALUE
 rb_winevt_query_seek(VALUE self, VALUE bookmark_or_flag)
 {
@@ -252,7 +312,7 @@ rb_winevt_query_close_handle(VALUE self)
 
   TypedData_Get_Struct(self, struct WinevtQuery, &rb_winevt_query_type, winevtQuery);
 
-  for (int i = 0; i < winevtQuery->count; i++){
+  for (int i = 0; i < winevtQuery->count; i++) {
     if (winevtQuery->hEvents[i] != NULL) {
       EvtClose(winevtQuery->hEvents[i]);
       winevtQuery->hEvents[i] = NULL;
@@ -280,6 +340,16 @@ rb_winevt_query_each_yield(VALUE self)
   return Qnil;
 }
 
+/*
+ * Enumerate to obtain Windows EventLog contents.
+ *
+ * This method yields the following:
+ * (Stringified EventLog, Stringified detail message, Stringified
+ * insert values)
+ *
+ * @yield (String,String,String)
+ *
+ */
 static VALUE
 rb_winevt_query_each(VALUE self)
 {
@@ -292,6 +362,11 @@ rb_winevt_query_each(VALUE self)
   return Qnil;
 }
 
+/*
+ * This method returns whether render as xml or not.
+ *
+ * @return [Boolean]
+ */
 static VALUE
 rb_winevt_query_render_as_xml_p(VALUE self)
 {
@@ -302,6 +377,11 @@ rb_winevt_query_render_as_xml_p(VALUE self)
   return winevtQuery->renderAsXML ? Qtrue : Qfalse;
 }
 
+/*
+ * This method specifies whether render as xml or not.
+ *
+ * @param rb_render_as_xml [Boolean]
+ */
 static VALUE
 rb_winevt_query_set_render_as_xml(VALUE self, VALUE rb_render_as_xml)
 {
@@ -322,12 +402,44 @@ Init_winevt_query(VALUE rb_cEventLog)
 
   rb_cFlag = rb_define_module_under(rb_cQuery, "Flag");
 
+  /* clang-format off */
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekRelativeToFirst
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekRelativeToFirst
+   */
   rb_define_const(rb_cFlag, "RelativeToFirst", LONG2NUM(EvtSeekRelativeToFirst));
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekRelativeToLast
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekRelativeToLast
+   */
   rb_define_const(rb_cFlag, "RelativeToLast", LONG2NUM(EvtSeekRelativeToLast));
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekRelativeToCurrent
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekRelativeToCurrent
+   */
   rb_define_const(rb_cFlag, "RelativeToCurrent", LONG2NUM(EvtSeekRelativeToCurrent));
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekRelativeToBookmark
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekRelativeToBookmark
+   */
   rb_define_const(rb_cFlag, "RelativeToBookmark", LONG2NUM(EvtSeekRelativeToBookmark));
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekOriginMask
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekOriginMask
+   */
   rb_define_const(rb_cFlag, "OriginMask", LONG2NUM(EvtSeekOriginMask));
+  /*
+   * EVT_SEEK_FLAGS enumeration: EvtSeekStrict
+   * @since 0.6.0
+   * @see https://msdn.microsoft.com/en-us/windows/desktop/aa385575#EvtSeekStrict
+   */
   rb_define_const(rb_cFlag, "Strict", LONG2NUM(EvtSeekStrict));
+  /* clang-format on */
 
   rb_define_method(rb_cQuery, "initialize", rb_winevt_query_initialize, 2);
   rb_define_method(rb_cQuery, "next", rb_winevt_query_next, 0);

data/ext/winevt/winevt_subscribe.c

@@ -1,5 +1,31 @@
 #include <winevt_c.h>
 
+/* clang-format off */
+/*
+ * Document-class: Winevt::EventLog::Subscribe
+ *
+ * Subscribe Windows EventLog channel.
+ *
+ * @example
+ *  require 'winevt'
+ *
+ *  @subscribe = Winevt::EventLog::Subscribe.new
+ *  @subscribe.tail = true
+ *  @subscribe.rate_limit = 80
+ *  @subscribe.subscribe(
+ *    "Application", "*[System[(Level <= 4) and TimeCreated[timediff(@SystemTime) <= 86400000]]]"
+ *  )
+ *  while true do
+ *    @subscribe.each do |eventlog, message, string_inserts|
+ *      puts ({eventlog: eventlog, data: message})
+ *    end
+ *    sleep(0.1)
+ *  end
+ *
+ * @see https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtsubscribe
+ */
+/* clang-format on */
+
 static void subscribe_free(void* ptr);
 
 static const rb_data_type_t rb_winevt_subscribe_type = { "winevt/subscribe",
@@ -44,6 +70,12 @@ rb_winevt_subscribe_alloc(VALUE klass)
   return obj;
 }
 
+/*
+ * Initalize Subscribe class.
+ *
+ * @return [Subscribe]
+ *
+ */
 static VALUE
 rb_winevt_subscribe_initialize(VALUE self)
 {
@@ -60,6 +92,11 @@ rb_winevt_subscribe_initialize(VALUE self)
   return Qnil;
 }
 
+/*
+ * This method specifies whether tailing or not.
+ *
+ * @param rb_tailing_p [Boolean]
+ */
 static VALUE
 rb_winevt_subscribe_set_tail(VALUE self, VALUE rb_tailing_p)
 {
@@ -73,8 +110,13 @@ rb_winevt_subscribe_set_tail(VALUE self, VALUE rb_tailing_p)
   return Qnil;
 }
 
+/*
+ * This method returns whether tailing or not.
+ *
+ * @return [Boolean]
+ */
 static VALUE
-rb_winevt_subscribe_tail_p(VALUE self, VALUE rb_flag)
+rb_winevt_subscribe_tail_p(VALUE self)
 {
   struct WinevtSubscribe* winevtSubscribe;
 
@@ -84,6 +126,16 @@ rb_winevt_subscribe_tail_p(VALUE self, VALUE rb_flag)
   return winevtSubscribe->tailing ? Qtrue : Qfalse;
 }
 
+/*
+ * Subscribe into a Windows EventLog channel.
+ *
+ * @overload subscribe(path, query, options={})
+ *   @param path [String] Subscribe Channel
+ *   @param query [String] Query string for channel
+ *   @option options [Bookmark] bookmark Bookmark class instance.
+ * @return [Boolean]
+ *
+ */
 static VALUE
 rb_winevt_subscribe_subscribe(int argc, VALUE* argv, VALUE self)
 {
@@ -91,8 +143,8 @@ rb_winevt_subscribe_subscribe(int argc, VALUE* argv, VALUE self)
   EVT_HANDLE hSubscription = NULL, hBookmark = NULL;
   HANDLE hSignalEvent;
   DWORD len, flags = 0L;
-  VALUE wpathBuf, wqueryBuf;
-  PWSTR path, query;
+  VALUE wpathBuf, wqueryBuf, wBookmarkBuf;
+  PWSTR path, query, bookmarkXml;
   DWORD status = ERROR_SUCCESS;
   struct WinevtSubscribe* winevtSubscribe;
 
@@ -105,8 +157,24 @@ rb_winevt_subscribe_subscribe(int argc, VALUE* argv, VALUE self)
   Check_Type(rb_path, T_STRING);
   Check_Type(rb_query, T_STRING);
 
-  if (rb_obj_is_kind_of(rb_bookmark, rb_cBookmark)) {
-    hBookmark = EventBookMark(rb_bookmark)->bookmark;
+  if (rb_obj_is_kind_of(rb_bookmark, rb_cString)) {
+    // bookmarkXml : To wide char
+    len = MultiByteToWideChar(
+        CP_UTF8, 0, RSTRING_PTR(rb_bookmark), RSTRING_LEN(rb_bookmark), NULL, 0);
+    bookmarkXml = ALLOCV_N(WCHAR, wBookmarkBuf, len + 1);
+    MultiByteToWideChar(CP_UTF8,
+                        0,
+                        RSTRING_PTR(rb_bookmark),
+                        RSTRING_LEN(rb_bookmark),
+                        bookmarkXml,
+                        len);
+    bookmarkXml[len] = L'\0';
+    hBookmark = EvtCreateBookmark(bookmarkXml);
+    ALLOCV_END(wBookmarkBuf);
+    if (hBookmark == NULL) {
+      status = GetLastError();
+      raise_system_error(rb_eWinevtQueryError, status);
+    }
   }
 
   // path : To wide char
@@ -134,6 +202,10 @@ rb_winevt_subscribe_subscribe(int argc, VALUE* argv, VALUE self)
 
   hSubscription =
     EvtSubscribe(NULL, hSignalEvent, path, query, hBookmark, NULL, NULL, flags);
+  if (!hSubscription) {
+    status = GetLastError();
+    raise_system_error(rb_eWinevtQueryError, status);
+  }
 
   ALLOCV_END(wpathBuf);
   ALLOCV_END(wqueryBuf);
@@ -144,18 +216,17 @@ rb_winevt_subscribe_subscribe(int argc, VALUE* argv, VALUE self)
     winevtSubscribe->bookmark = hBookmark;
   } else {
     winevtSubscribe->bookmark = EvtCreateBookmark(NULL);
+    if (winevtSubscribe->bookmark == NULL) {
+      status = GetLastError();
+      raise_system_error(rb_eWinevtQueryError, status);
+    }
   }
 
-  status = GetLastError();
-
-  if (status == ERROR_SUCCESS)
-    return Qtrue;
-
-  return Qfalse;
+  return Qtrue;
 }
 
 BOOL
-is_rate_limit_exceeded(struct WinevtSubscribe *winevtSubscribe)
+is_rate_limit_exceeded(struct WinevtSubscribe* winevtSubscribe)
 {
   time_t now;
 
@@ -176,7 +247,7 @@ is_rate_limit_exceeded(struct WinevtSubscribe *winevtSubscribe)
 }
 
 void
-update_to_reflect_rate_limit_state(struct WinevtSubscribe *winevtSubscribe, ULONG count)
+update_to_reflect_rate_limit_state(struct WinevtSubscribe* winevtSubscribe, ULONG count)
 {
   time_t lastTime = 0;
 
@@ -188,6 +259,15 @@ update_to_reflect_rate_limit_state(struct WinevtSubscribe *winevtSubscribe, ULON
   winevtSubscribe->currentRate += count;
 }
 
+/*
+ * Handle the next values. Since v0.6.0, this method is used for
+ * testing only. Please use #each instead.
+ *
+ * @return [Boolean]
+ *
+ * @see each
+ */
+
 static VALUE
 rb_winevt_subscribe_next(VALUE self)
 {
@@ -203,8 +283,12 @@ rb_winevt_subscribe_next(VALUE self)
     return Qfalse;
   }
 
-  if (!EvtNext(winevtSubscribe->subscription, SUBSCRIBE_ARRAY_SIZE,
-              hEvents, INFINITE, 0, &count)) {
+  if (!EvtNext(winevtSubscribe->subscription,
+               SUBSCRIBE_ARRAY_SIZE,
+               hEvents,
+               INFINITE,
+               0,
+               &count)) {
     status = GetLastError();
     if (ERROR_NO_MORE_ITEMS != status) {
       return Qfalse;
@@ -297,6 +381,16 @@ rb_winevt_subscribe_each_yield(VALUE self)
   return Qnil;
 }
 
+/*
+ * Enumerate to obtain Windows EventLog contents.
+ *
+ * This method yields the following:
+ * (Stringified EventLog, Stringified detail message, Stringified
+ * insert values)
+ *
+ * @yield (String,String,String)
+ *
+ */
 static VALUE
 rb_winevt_subscribe_each(VALUE self)
 {
@@ -310,6 +404,11 @@ rb_winevt_subscribe_each(VALUE self)
   return Qnil;
 }
 
+/*
+ * This method renders bookmark content which is related to Subscribe class instance.
+ *
+ * @return [String]
+ */
 static VALUE
 rb_winevt_subscribe_get_bookmark(VALUE self)
 {
@@ -321,6 +420,12 @@ rb_winevt_subscribe_get_bookmark(VALUE self)
   return render_to_rb_str(winevtSubscribe->bookmark, EvtRenderBookmark);
 }
 
+/*
+ * This method returns rate limit value.
+ *
+ * @since 0.6.0
+ * @return [Integer]
+ */
 static VALUE
 rb_winevt_subscribe_get_rate_limit(VALUE self)
 {
@@ -332,6 +437,12 @@ rb_winevt_subscribe_get_rate_limit(VALUE self)
   return INT2NUM(winevtSubscribe->rateLimit);
 }
 
+/*
+ * This method specifies rate limit value.
+ *
+ * @since 0.6.0
+ * @param rb_rate_limit [Integer] rate_limit value
+ */
 static VALUE
 rb_winevt_subscribe_set_rate_limit(VALUE self, VALUE rb_rate_limit)
 {
@@ -343,10 +454,8 @@ rb_winevt_subscribe_set_rate_limit(VALUE self, VALUE rb_rate_limit)
 
   rateLimit = NUM2LONG(rb_rate_limit);
 
-  if ((rateLimit != SUBSCRIBE_RATE_INFINITE) &&
-      (rateLimit < 10 || rateLimit % 10)) {
-    rb_raise(rb_eArgError,
-             "Specify a multiples of 10 or RATE_INFINITE constant");
+  if ((rateLimit != SUBSCRIBE_RATE_INFINITE) && (rateLimit < 10 || rateLimit % 10)) {
+    rb_raise(rb_eArgError, "Specify a multiples of 10 or RATE_INFINITE constant");
   } else {
     winevtSubscribe->rateLimit = rateLimit;
   }
@@ -354,6 +463,12 @@ rb_winevt_subscribe_set_rate_limit(VALUE self, VALUE rb_rate_limit)
   return Qnil;
 }
 
+/*
+ * This method returns whether render as xml or not.
+ *
+ * @since 0.6.0
+ * @return [Boolean]
+ */
 static VALUE
 rb_winevt_subscribe_render_as_xml_p(VALUE self)
 {
@@ -365,6 +480,12 @@ rb_winevt_subscribe_render_as_xml_p(VALUE self)
   return winevtSubscribe->renderAsXML ? Qtrue : Qfalse;
 }
 
+/*
+ * This method specifies whether render as xml or not.
+ *
+ * @since 0.6.0
+ * @param rb_render_as_xml [Boolean]
+ */
 static VALUE
 rb_winevt_subscribe_set_render_as_xml(VALUE self, VALUE rb_render_as_xml)
 {
@@ -385,6 +506,10 @@ Init_winevt_subscribe(VALUE rb_cEventLog)
 
   rb_define_alloc_func(rb_cSubscribe, rb_winevt_subscribe_alloc);
 
+  /*
+   * For Subscribe#rate_limit=. It represents unspecified rate limit.
+   * @since 0.6.0
+   */
   rb_define_const(rb_cSubscribe, "RATE_INFINITE", SUBSCRIBE_RATE_INFINITE);
 
   rb_define_method(rb_cSubscribe, "initialize", rb_winevt_subscribe_initialize, 0);
@@ -396,6 +521,8 @@ Init_winevt_subscribe(VALUE rb_cEventLog)
   rb_define_method(rb_cSubscribe, "tail=", rb_winevt_subscribe_set_tail, 1);
   rb_define_method(rb_cSubscribe, "rate_limit", rb_winevt_subscribe_get_rate_limit, 0);
   rb_define_method(rb_cSubscribe, "rate_limit=", rb_winevt_subscribe_set_rate_limit, 1);
-  rb_define_method(rb_cSubscribe, "render_as_xml?", rb_winevt_subscribe_render_as_xml_p, 0);
-  rb_define_method(rb_cSubscribe, "render_as_xml=", rb_winevt_subscribe_set_render_as_xml, 1);
+  rb_define_method(
+    rb_cSubscribe, "render_as_xml?", rb_winevt_subscribe_render_as_xml_p, 0);
+  rb_define_method(
+    rb_cSubscribe, "render_as_xml=", rb_winevt_subscribe_set_render_as_xml, 1);
 }

data/ext/winevt/winevt_utils.cpp

@@ -19,6 +19,28 @@ wstr_to_rb_str(UINT cp, const WCHAR* wstr, int clen)
   return str;
 }
 
+void
+raise_system_error(VALUE error, DWORD errorCode)
+{
+  WCHAR msgBuf[256] = { 0 };
+  VALUE errorMessage;
+
+  FormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
+                 NULL,
+                 errorCode,
+                 MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+                 msgBuf,
+                 _countof(msgBuf),
+                 NULL);
+  errorMessage = wstr_to_rb_str(CP_UTF8, msgBuf, -1);
+
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wformat="
+#pragma GCC diagnostic ignored "-Wformat-extra-args"
+  rb_raise(error, "ErrorCode: %lu\nError: %" PRIsVALUE "\n", errorCode, errorMessage);
+#pragma GCC diagnostic pop
+}
+
 VALUE
 render_to_rb_str(EVT_HANDLE handle, DWORD flags)
 {
@@ -44,17 +66,8 @@ render_to_rb_str(EVT_HANDLE handle, DWORD flags)
     EvtRender(nullptr, handle, flags, bufferSize, buffer, &bufferSizeUsed, &count);
   if (!succeeded) {
     DWORD status = GetLastError();
-    CHAR msgBuf[256];
-
-    FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
-                   nullptr,
-                   status,
-                   MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
-                   msgBuf,
-                   _countof(msgBuf),
-                   nullptr);
     ALLOCV_END(vbuffer);
-    rb_raise(rb_eWinevtQueryError, "ErrorCode: %lu\nError: %s\n", status, msgBuf);
+    raise_system_error(rb_eWinevtQueryError, status);
   }
 
   result = wstr_to_rb_str(CP_UTF8, buffer, -1);
@@ -284,19 +297,9 @@ get_values(EVT_HANDLE handle)
                         &propCount);
   if (!succeeded) {
     DWORD status = GetLastError();
-    CHAR msgBuf[256];
-
     ALLOCV_END(vbuffer);
     EvtClose(renderContext);
-
-    FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
-                   nullptr,
-                   status,
-                   MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
-                   msgBuf,
-                   _countof(msgBuf),
-                   nullptr);
-    rb_raise(rb_eWinevtQueryError, "ErrorCode: %lu\nError: %s\n", status, msgBuf);
+    raise_system_error(rb_eWinevtQueryError, status);
   }
 
   userValues = extract_user_evt_variants(pRenderedValues, propCount);
@@ -437,7 +440,6 @@ get_description(EVT_HANDLE handle)
   ULONG bufferSizeNeeded = 0;
   ULONG status, count;
   std::vector<WCHAR> result;
-  CHAR msgBuf[256];
   EVT_HANDLE hMetadata = nullptr;
 
   static PCWSTR eventProperties[] = { L"Event/System/Provider/@Name" };
@@ -460,14 +462,7 @@ get_description(EVT_HANDLE handle)
   }
 
   if (status != ERROR_SUCCESS) {
-    FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
-                   nullptr,
-                   status,
-                   MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
-                   msgBuf,
-                   sizeof(msgBuf),
-                   nullptr);
-    rb_raise(rb_eWinevtQueryError, "ErrorCode: %lu\nError: %s\n", status, msgBuf);
+    raise_system_error(rb_eWinevtQueryError, status);
   }
 
   // Obtain buffer as EVT_VARIANT pointer. To avoid ErrorCide 87 in EvtRender.
@@ -524,8 +519,8 @@ render_system_event(EVT_HANDLE hEvent)
 
   hContext = EvtCreateRenderContext(0, NULL, EvtRenderContextSystem);
   if (NULL == hContext) {
-    rb_raise(rb_eWinevtQueryError,
-             "Failed to create renderContext with %lu\n", GetLastError());
+    rb_raise(
+      rb_eWinevtQueryError, "Failed to create renderContext with %lu\n", GetLastError());
   }
 
   if (!EvtRender(hContext,
@@ -549,8 +544,7 @@ render_system_event(EVT_HANDLE hEvent)
                   &dwPropertyCount);
       } else {
         EvtClose(hContext);
-        rb_raise(rb_eRuntimeError,
-             "Failed to malloc memory with %lu\n", status);
+        rb_raise(rb_eRuntimeError, "Failed to malloc memory with %lu\n", status);
       }
     }
 
@@ -559,8 +553,7 @@ render_system_event(EVT_HANDLE hEvent)
       EvtClose(hContext);
       ALLOCV_END(vRenderedValues);
 
-      rb_raise(rb_eWinevtQueryError,
-               "EvtRender failed with %lu\n", status);
+      rb_raise(rb_eWinevtQueryError, "EvtRender failed with %lu\n", status);
     }
   }
 
@@ -605,8 +598,11 @@ render_system_event(EVT_HANDLE hEvent)
                (EvtVarTypeNull == pRenderedValues[EvtSystemOpcode].Type)
                  ? INT2NUM(0)
                  : INT2NUM(pRenderedValues[EvtSystemOpcode].ByteVal));
-  _snprintf_s(buffer, _countof(buffer), _TRUNCATE,
-              "0x%llx", pRenderedValues[EvtSystemKeywords].UInt64Val);
+  _snprintf_s(buffer,
+              _countof(buffer),
+              _TRUNCATE,
+              "0x%llx",
+              pRenderedValues[EvtSystemKeywords].UInt64Val);
   rb_hash_aset(hash,
                rb_str_new2("Keywords"),
                (EvtVarTypeNull == pRenderedValues[EvtSystemKeywords].Type)

data/lib/winevt.rb

@@ -3,6 +3,7 @@ begin
 rescue LoadError
   require "winevt/winevt"
 end
+require "winevt/bookmark"
 require "winevt/query"
 require "winevt/subscribe"
 require "winevt/version"

data/lib/winevt/bookmark.rb

@@ -0,0 +1,6 @@
+module Winevt
+  class EventLog
+    class Bookmark
+    end
+  end
+end

data/lib/winevt/subscribe.rb

@@ -1,6 +1,15 @@
 module Winevt
   class EventLog
     class Subscribe
+      alias_method :subscribe_raw, :subscribe
+
+      def subscribe(path, query, bookmark = nil)
+        if bookmark.is_a?(Winevt::EventLog::Bookmark)
+          subscribe_raw(path, query, bookmark.render)
+        else
+          subscribe_raw(path, query)
+        end
+      end
     end
   end
 end

data/lib/winevt/version.rb

@@ -1,3 +1,3 @@
 module Winevt
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/winevt_c.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake-compiler", "~> 1.0"
   spec.add_development_dependency "rake-compiler-dock", "~> 0.7.2"
   spec.add_development_dependency "test-unit", "~> 3.2"
+  spec.add_development_dependency "yard", "~> 0.9"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: winevt_c
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Hiroshi Hatake
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-09 00:00:00.000000000 Z
+date: 2019-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Windows Event Log API bindings from winevt.h.
 email:
 - cosmo0920.wp@gmail.com
@@ -116,6 +130,7 @@ files:
 - ext/winevt/winevt_subscribe.c
 - ext/winevt/winevt_utils.cpp
 - lib/winevt.rb
+- lib/winevt/bookmark.rb
 - lib/winevt/query.rb
 - lib/winevt/subscribe.rb
 - lib/winevt/version.rb