basis/windows/com/wrapper/wrapper-docs.factor

   1 USING: help.markup help.syntax io kernel math quotations\r
   2 multiline alien windows.com windows.com.syntax continuations\r
   3 destructors ;\r
   4 IN: windows.com.wrapper\r
   5 \r
   6 HELP: <com-wrapper>\r
   7 { $values { "implementations" "an assoc relating COM interface names to arrays of quotations implementing that interface" } { "wrapper" "a " { $link com-wrapper } " tuple" } }\r
   8 { $description "Constructs a " { $link com-wrapper } " tuple. Each key in the " { $snippet "implementations" } " assoc must be the name of an interface defined with " { $link POSTPONE: COM-INTERFACE: } ". The corresponding value must be an array of quotations implementing the methods of that interface in order, including those of its parent interfaces. The " { $snippet "IUnknown" } " methods (" { $link IUnknown::QueryInterface } ", " { $link IUnknown::AddRef } ", and " { $link IUnknown::Release } ") will be defined automatically and must not be specified in the array. These quotations should have stack effects mirroring those of the interface methods being implemented; for example, a method " { $snippet "void foobar ( int foo, int bar )" } " should be implemented with a quotation of effect " { $snippet "( this foo bar -- )" } ". The " { $snippet "this" } " parameter (that is, the leftmost parameter of any COM method) will be automatically converted from an alien pointer to the underlying Factor object before the quotation is invoked.\n\nThe resulting wrapper can be applied to a Factor object using the " { $link com-wrap } " word. The COM interface pointer returned by " { $snippet "com-wrap" } " can then be passed to C functions requiring a COM object as a parameter. The vtables constructed by " { $snippet "<com-wrapper>" } " are stored on the non-GC heap in order to be accessible to C functions; when the wrapper object and its vtables are no longer needed, the object's resources must be freed using " { $link dispose } ".\n\nExample:" }\r
   9 { $code <"\r
  10 COM-INTERFACE: ISimple IUnknown {216fb341-0eb2-44b1-8edb-60b76e353abc}\r
  11     HRESULT returnOK ( )\r
  12     HRESULT returnError ( ) ;\r
  13 \r
  14 COM-INTERFACE: IInherited ISimple {9620ecec-8438-423b-bb14-86f835aa40dd}\r
  15     int getX ( )\r
  16     void setX ( int newX ) ;\r
  17 \r
  18 COM-INTERFACE: IUnrelated IUnknown {b06ac3f4-30e4-406b-a7cd-c29cead4552c}\r
  19     int xPlus ( int y )\r
  20     int xMulAdd ( int mul, int add ) ;\r
  21 \r
  22 {\r
  23     { "IInherited" {\r
  24         [ drop S_OK ]    ! ISimple::returnOK\r
  25         [ drop E_FAIL ]  ! ISimple::returnError\r
  26         [ x>> ]          ! IInherited::getX\r
  27         [ >>x drop ]     ! IInherited::setX\r
  28     } }\r
  29     { "IUnrelated" {\r
  30         [ swap x>> + ]   ! IUnrelated::xPlus\r
  31         [ spin x>> * + ] ! IUnrealted::xMulAdd\r
  32     } }\r
  33 } <com-wrapper>\r
  34 "> } ;\r
  35 \r
  36 HELP: com-wrap\r
  37 { $values { "object" "The factor object to wrap" } { "wrapper" "A " { $link com-wrapper } " object" } { "wrapped-object" "A COM object referencing " { $snippet "object" } } }\r
  38 { $description "Allocates a COM object using the implementations in the " { $snippet "wrapper" } " object for the vtables and " { $snippet "object" } " for the \"this\" parameter. The COM object is allocated on the heap with an initial reference count of 1. The object will automatically deallocate itself when its reference count reaches 0 as a result of calling " { $link IUnknown::Release } " or " { $link com-release } " on it.\n\nNote that if " { $snippet "wrapper" } " implements multiple interfaces, you cannot count on the returned COM object pointer implementing any particular interface beyond " { $snippet "IUnknown" } ". You will need to use " { $link com-query-interface } " or " { $link IUnknown::QueryInterface } " to ask the object for the particular interface you need." } ;\r
  39 \r
  40 HELP: com-wrapper\r
  41 { $class-description "The tuple class used to store COM wrapper information. Objects of this class should be treated as opaque by user code. A com-wrapper can be constructed using the " { $link <com-wrapper> } " constructor and applied to a Factor object using " { $link com-wrap } ". When no longer needed, release the com-wrapper's internally allocated data with " { $link dispose } "." } ;\r