basis/windows/com/com-docs.factor

   1 USING: help.markup help.syntax io kernel math quotations\r
   2 multiline destructors ;\r
   3 IN: windows.com\r
   4 \r
   5 HELP: com-query-interface\r
   6 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } { "iid" "An interface GUID (IID)" } { "interface'" "Pointer to a COM interface implementing the interface indicated by " { $snippet "iid" } } }\r
   7 { $description "A small wrapper around " { $link IUnknown::QueryInterface } ". Queries " { $snippet "interface" } " to see if it implements the interface indicated by " { $snippet "iid" } ". Returns a pointer to the " { $snippet "iid" } " interface if implemented, or raises an error if the object does not implement the interface.\n\nCOM memory management conventions state that the returned pointer must be released using " { $link com-release } " when it is no longer needed." } ;\r
   8 \r
   9 HELP: com-add-ref\r
  10 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }\r
  11 { $description "A small wrapper around " { $link IUnknown::AddRef } ". Increments the reference count on " { $snippet "interface" } ", keeping it on the stack. The reference count must be decremented with " { $link com-release } " when the reference is no longer held." } ;\r
  12 \r
  13 HELP: com-release\r
  14 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }\r
  15 { $description "A small wrapper around " { $link IUnknown::Release } ". Decrements the reference count on " { $snippet "interface" } ", releasing the underlying object if the reference count has reached zero." } ;\r
  16 \r
  17 HELP: &com-release\r
  18 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }\r
  19 { $description "Marks the given COM interface for unconditional release via " { $link com-release } " at the end of the enclosing " { $link with-destructors } " scope." } ;\r
  20 \r
  21 HELP: |com-release\r
  22 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }\r
  23 { $description "Marks the given COM interface for release via " { $link com-release } " in the event of an error at the end of the enclosing " { $link with-destructors } " scope." } ;\r
  24 \r
  25 { com-release &com-release |com-release } related-words\r
  26 \r