basis/windows/com/com-docs.factor

   1 USING: help.markup help.syntax io kernel math quotations
   2 multiline destructors ;
   3 IN: windows.com
   4
   5 HELP: com-query-interface
   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" } } }
   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." } ;
   8
   9 HELP: com-add-ref
  10 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }
  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." } ;
  12
  13 HELP: com-release
  14 { $values { "interface" "Pointer to a COM interface implementing " { $snippet "IUnknown" } } }
  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." } ;
  16
  17 HELP: &com-release
  18 { $values { "alien" "pointer to a COM interface implementing " { $snippet "IUnknown" } } }
  19 { $description "Marks the given COM interface for unconditional release via " { $link com-release } " at the end of the enclosing " { $link with-destructors } " scope." } ;
  20
  21 HELP: |com-release
  22 { $values { "alien" "pointer to a COM interface implementing " { $snippet "IUnknown" } } }
  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." } ;
  24
  25 { com-release &com-release |com-release } related-words