home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 October / Chip_2001-10_cd1.bin / zkuste / vbasic / DATA / Utility / content.exe / LITGenComponent / litgen.idl < prev   
Text File  |  2000-09-29  |  24KB  |  547 lines
  1. //+-----------------------------------------------------------------------
  2. //  MS Bookmaker
  3. //  Copyright (c) 1999-2000  Microsoft Corporation.  All Rights Reserved.
  4. //
  5. //  File:       litgen.idl
  6. //
  7. //  Contents:   interface definitions for LIT generator component
  8. //
  9. //  Interfaces: ILITCallback
  10. //              ILITTag
  11. //              ILITParserHost
  12. //              ILITCSSHost
  13. //              ILITImageHost
  14. //              ILITWriter
  15. //
  16. //  Notes:      See the interface documentation on ILITWriter for a top-level
  17. //              overview of how to use litgen.
  18. //              Every interface pointer that crosses these interfaces is an
  19. //              IUnknown; this is to force the receiver to query for the
  20. //              interface IID they need, since mismatches are possible when
  21. //              relying on the type name alone.
  22. //
  23. //  Author:     Nate Lewis (nlewis@microsoft.com)
  24. //
  25. //------------------------------------------------------------------------
  26.  
  27. import "unknwn.idl";
  28.  
  29. //+-----------------------------------------------------------------------
  30. //
  31. //  Interface: ILITCallback
  32. //
  33. //  Summary:   Simple interface for receiving text messages.  The litgen
  34. //             client implements this and passes it to ILITWriter::SetCallback();
  35. //             Message() will be called at various times during content prep.
  36. //
  37. //             Message codes correspond 1:1 to the stringtable entries used to create the text
  38. //             messages sent through ILITCallback.  They are intended to allow a client to
  39. //             distinguish classes of codes, to allow more advanced behavior than simply
  40. //             bailing out, and to allow filtering of certain messages if desired.  (Hiding
  41. //             warnings from the user without giving them a choice about it is strongly
  42. //             discouraged, however; we suggest a Details>>-style foldup dialog.)
  43. //
  44. //             In most cases, LITGen has no contextual sense to report in an error; LITGen
  45. //             can't know what line of the source document it's on, for example.  The
  46. //             implementation of ILITCallback should retrieve file and line information from
  47. //             the parser, and present it along with the error message that comes from litgen.
  48. //
  49. //             The message codes are structured; see the comments in litgen_msgcodes.h.
  50. //
  51. //------------------------------------------------------------------------
  52. [object, uuid(6BC62165-B91C-4993-8002-5BC30B2D1196)]
  53. interface ILITCallback : IUnknown
  54. {
  55.     //+-----------------------------------------------------------------------
  56.     //
  57.     //  Function:       Message
  58.     //  Description:    receives a warning, error, or informational message
  59.     //  Parameters:     iType - message type indicator:
  60.     //                       0: fatal error
  61.     //                       1: warning
  62.     //                      -1: informational message
  63.     //                  iMessageCode - see above
  64.     //                  pwszMessage - null-terminated message text
  65.     //  Returns:        S_OK
  66.     //  Notes:
  67.     //
  68.     //------------------------------------------------------------------------
  69.     HRESULT Message([in] int iType, [in] int iMessageCode, 
  70.                     [in, string] const wchar_t* pwszMessage);
  71. };
  72.  
  73. //+-----------------------------------------------------------------------
  74. //
  75. //  Interface: ILITTag
  76. //
  77. //  Summary:   Write-only interface to a tag.  litgen clients should ask
  78. //             ILITParserHost for a blank tag, populate its name and attributes
  79. //             through this interface, then give it back to the host, with Tag().
  80. //
  81. //------------------------------------------------------------------------
  82. [object, uuid(D655ECEB-829A-11d3-929B-00C04F68FC0F)]
  83. interface ILITTag : IUnknown
  84. {
  85.     //+-----------------------------------------------------------------------
  86.     //
  87.     //  Function:       SetName
  88.     //  Description:    sets the name of a new tag
  89.     //  Parameters:     pwchName, cwchName - pointer to and size of tag name
  90.     //  Returns:        S_OK
  91.     //                  E_INVALIDARG
  92.     //                  E_OUTOFMEMORY
  93.     //                  E_FAIL
  94.     //  Notes:          pwchName need not be terminated.
  95.     //
  96.     //------------------------------------------------------------------------
  97.     HRESULT SetName([in, size_is(cwchName)] const wchar_t* pwchName, [in] ULONG cwchName);
  98.  
  99.     //+-----------------------------------------------------------------------
  100.     //
  101.     //  Function:       AddAttribute
  102.     //  Description:    adds an attribute to a new tag
  103.     //  Parameters:     pwchName, cwchName - pointer to and size of attribute name
  104.     //                  pwchValue, cwchValue - pointer to and size of attribute value
  105.     //  Returns:        S_OK
  106.     //                  E_INVALIDARG
  107.     //                  E_OUTOFMEMORY
  108.     //                  E_FAIL
  109.     //  Notes:          pwchName and pwchValue need not be terminated.
  110.     //
  111.     //------------------------------------------------------------------------
  112.     HRESULT AddAttribute([in, size_is(cwchName)] const wchar_t* pwchName, [in] ULONG cwchName,
  113.                         [in, size_is(cwchValue)] const wchar_t* pwchValue, [in] ULONG cwchValue);
  114. };
  115.  
  116. //+-----------------------------------------------------------------------
  117. //
  118. //  Interface: ILITHost
  119. //
  120. //  Summary:   Common interface to the three 'identity' properties implemented on
  121. //             all hosts.
  122. //
  123. //------------------------------------------------------------------------
  124. [object, uuid(65E8FC16-8661-11d3-929C-00C04F68FC0F)]
  125. interface ILITHost : IUnknown
  126. {
  127.     //+-----------------------------------------------------------------------
  128.     //
  129.     //  Function:       GetId
  130.     //  Description:    returns the manifest ID of the item being parsed
  131.     //  Parameters:     pbstr - pointer to BSTR to receive the string
  132.     //  Returns:        S_OK
  133.     //                  E_INVALIDARG
  134.     //                  E_OUTOFMEMORY
  135.     //                  E_UNEXPECTED
  136.     //                  E_FAIL
  137.     //  Notes:          caller must SysFreeString().
  138.     //
  139.     //------------------------------------------------------------------------
  140.     HRESULT GetId([out, retval] BSTR* pbstrId);
  141.  
  142.     //+-----------------------------------------------------------------------
  143.     //
  144.     //  Function:       GetFilename
  145.     //  Description:    returns the filename of the item being parsed
  146.     //  Parameters:     pbstr - pointer to BSTR to receive the string
  147.     //  Returns:        S_OK
  148.     //                  E_INVALIDARG
  149.     //                  E_OUTOFMEMORY
  150.     //                  E_UNEXPECTED
  151.     //                  E_FAIL
  152.     //  Notes:          caller must SysFreeString().
  153.     //
  154.     //------------------------------------------------------------------------
  155.     HRESULT GetFilename([out, retval] BSTR* pbstrFilename);
  156.  
  157.     //+-----------------------------------------------------------------------
  158.     //
  159.     //  Function:       GetMimeType
  160.     //  Description:    returns the mime type of the item being parsed
  161.     //  Parameters:     pbstr - pointer to BSTR to receive the string
  162.     //  Returns:        S_OK
  163.     //                  E_INVALIDARG
  164.     //                  E_OUTOFMEMORY
  165.     //                  E_UNEXPECTED
  166.     //                  E_FAIL
  167.     //  Notes:          caller must SysFreeString().
  168.     //
  169.     //------------------------------------------------------------------------
  170.     HRESULT GetMimeType([out, retval] BSTR* pbstrMimeType);
  171. };
  172.  
  173. //+-----------------------------------------------------------------------
  174. //
  175. //  Interface: ILITParserHost
  176. //
  177. //  Summary:   Host to a content parser.  Both content files and metadata must
  178. //             be parsed by the litgen client, and fed to this interface as a
  179. //             stream of Tag, Text, and EndChildren notifications.
  180. //
  181. //------------------------------------------------------------------------
  182.  
  183. [object, uuid(607A85B7-59C1-4b22-B873-A36334740661)]
  184. interface ILITParserHost : ILITHost
  185. {
  186.     //+-----------------------------------------------------------------------
  187.     //
  188.     //  Function:       NewTag
  189.     //  Description:    Creates a new, empty tag.
  190.     //  Parameters:     ppTag - pointer to interface pointer
  191.     //  Returns:        S_OK
  192.     //                  E_INVALIDARG
  193.     //                  E_OUTOFMEMORY
  194.     //                  E_FAIL
  195.     //  Notes:
  196.     //
  197.     //------------------------------------------------------------------------
  198.     HRESULT NewTag([out, retval] IUnknown** ppTag);
  199.  
  200.     //+-----------------------------------------------------------------------
  201.     //
  202.     //  Function:       Tag
  203.     //  Description:    Accepts notification of a tag in the content stream.
  204.     //  Parameters:     pTag - the populated tag
  205.     //                  fChildren - this should be true if the tag has children
  206.     //                      (either text or nested tags within the tag).
  207.     //  Returns:        S_OK
  208.     //                  E_INVALIDARG
  209.     //                  E_OUTOFMEMORY
  210.     //                  E_UNEXPECTED
  211.     //                  E_FAIL
  212.     //  Notes:          If fChildren is true, a matching EndChildren() will be
  213.     //                  required; if fChildren is false, EndChildren() must not
  214.     //                  be called for this tag.
  215.     //
  216.     //------------------------------------------------------------------------
  217.     HRESULT Tag([in] IUnknown* pTag, [in] BOOL fChildren);
  218.  
  219.     //+-----------------------------------------------------------------------
  220.     //
  221.     //  Function:       Text
  222.     //  Description:    Accepts notification of text in the content stream.
  223.     //  Parameters:     pwchText, cwchText - pointer to and length of the text.
  224.     //  Returns:        S_OK
  225.     //                  E_INVALIDARG
  226.     //                  E_OUTOFMEMORY
  227.     //                  E_UNEXPECTED
  228.     //                  E_FAIL
  229.     //  Notes:          Text need not be null-terminated, nor complete; a text
  230.     //                  run can be broken up into several sequential calls to
  231.     //                  Text(), if necessary.
  232.     //
  233.     //------------------------------------------------------------------------
  234.     HRESULT Text([in] const wchar_t* pwchText, [in] ULONG cwchText);
  235.  
  236.     //+-----------------------------------------------------------------------
  237.     //
  238.     //  Function:       EndChildren
  239.     //  Description:    Accepts notification of the end of a tag's children.
  240.     //  Parameters:
  241.     //  Returns:        S_OK
  242.     //                  E_OUTOFMEMORY
  243.     //                  E_UNEXPECTED
  244.     //                  E_FAIL
  245.     //  Notes:
  246.     //
  247.     //------------------------------------------------------------------------
  248.     HRESULT EndChildren();
  249.  
  250.     //+-----------------------------------------------------------------------
  251.     //
  252.     //  Function:       ExternalStylesheet
  253.     //  Description:    Accepts notification of an external stylesheet that is
  254.     //                  specified more or less independently from the document
  255.     //                  structure - for example, the <?xml-stylesheet?> PI in
  256.     //                  OEB documents.
  257.     //  Parameters:     pTag - a tag populated as if it were a <link> tag
  258.     //  Returns:        S_OK
  259.     //                  E_INVALIDARG
  260.     //                  E_OUTOFMEMORY
  261.     //                  E_UNEXPECTED
  262.     //                  E_FAIL
  263.     //  Notes:          Internally, such stylesheets are actually handled as
  264.     //                  <link> tags; this means that they will be held until
  265.     //                  a <head> is found (or synthesized for this purpose).
  266.     //                  As a result, any warnings arising from this call may
  267.     //                  not be sent to the callback immediately.
  268.     //
  269.     //------------------------------------------------------------------------
  270.     HRESULT ExternalStylesheet([in] IUnknown* pTag);
  271.  
  272.     //+-----------------------------------------------------------------------
  273.     //
  274.     //  Function:       Finish
  275.     //  Description:    Finalizes the content
  276.     //  Parameters:
  277.     //  Returns:        S_OK
  278.     //                  E_OUTOFMEMORY
  279.     //                  E_UNEXPECTED
  280.     //                  E_FAIL
  281.     //  Notes:
  282.     //
  283.     //------------------------------------------------------------------------
  284.     HRESULT Finish();
  285. };
  286.  
  287. //+-----------------------------------------------------------------------
  288. //
  289. //  Interface: ILITCSSHost
  290. //
  291. //  Summary:   Host for receiving CSS stylesheet data.  UTF8 and both forms of
  292. //             UTF16 are supported.
  293. //
  294. //------------------------------------------------------------------------
  295. [object, uuid(D7426056-FA2D-4d14-B36C-34D49A20D237)]
  296. interface ILITCSSHost : ILITHost
  297. {
  298.     //+-----------------------------------------------------------------------
  299.     //
  300.     //  Function:       Write
  301.     //  Description:    receives the text of the stylesheet
  302.     //  Parameters:     pb, cb - pointer to and size of the data
  303.     //                  pcbWritten - optional pointer to ULONG to receive the
  304.     //                      count of bytes actually written
  305.     //  Returns:        S_OK
  306.     //                  E_INVALIDARG
  307.     //                  E_OUTOFMEMORY
  308.     //                  E_UNEXPECTED
  309.     //                  E_FAIL
  310.     //  Notes:
  311.     //
  312.     //------------------------------------------------------------------------
  313.     HRESULT Write([in, size_is(cb)] const BYTE* pb, [in] ULONG cb, [out] ULONG* pcbWritten);
  314.  
  315.     //+-----------------------------------------------------------------------
  316.     //
  317.     //  Function:       Finish
  318.     //  Description:    Finalizes the CSS stream
  319.     //  Parameters:
  320.     //  Returns:        S_OK
  321.     //                  E_OUTOFMEMORY
  322.     //                  E_UNEXPECTED
  323.     //                  E_FAIL
  324.     //  Notes:          The CSS is actually parsed during Finish().
  325.     //
  326.     //------------------------------------------------------------------------
  327.     HRESULT Finish();
  328.  
  329.     //+-----------------------------------------------------------------------
  330.     //
  331.     //  Function:       GetCurrentLine
  332.     //  Description:    In case of error during Finish(), returns the current
  333.     //                  line of the parser
  334.     //  Parameters:
  335.     //  Returns:        S_OK
  336.     //                  E_INVALIDARG
  337.     //                  E_FAIL
  338.     //                  E_NOTIMPL
  339.     //  Notes:          Parse warnings and errors are sent during Finish(), when
  340.     //                  the client may be looking at </style>, for example; this
  341.     //                  method gives the offset in lines from the beginning of
  342.     //                  the CSS data.  The line number is not always available.
  343.     //
  344.     //------------------------------------------------------------------------
  345.     HRESULT GetCurrentLine([out, retval] ULONG* pcLine);
  346. };
  347.  
  348. //+-----------------------------------------------------------------------
  349. //
  350. //  Interface: ILITImageHost
  351. //
  352. //  Summary:   Host for receiving raw image file data.  Image files can be copied
  353. //             verbatim into this host.
  354. //
  355. //------------------------------------------------------------------------
  356. [object, uuid(D655ECEE-829A-11d3-929B-00C04F68FC0F)]
  357. interface ILITImageHost : ILITHost
  358. {
  359.     //+-----------------------------------------------------------------------
  360.     //
  361.     //  Function:       Write
  362.     //  Description:    receives the raw bytes of the image file
  363.     //  Parameters:     pb, cb - pointer to and size of the data
  364.     //                  pcbWritten - optional pointer to ULONG to receive the
  365.     //                      count of bytes actually written
  366.     //  Returns:        S_OK
  367.     //                  E_INVALIDARG
  368.     //                  E_OUTOFMEMORY
  369.     //                  E_FAIL
  370.     //  Notes:
  371.     //
  372.     //------------------------------------------------------------------------
  373.     HRESULT Write([in, size_is(cb)] const BYTE* pb, [in] ULONG cb, [out] ULONG* pcbWritten);
  374. };
  375.  
  376. //+-----------------------------------------------------------------------
  377. //
  378. //  Interface: ILITWriter
  379. //
  380. //  Summary:   This is the main interface to litgen.  The client should
  381. //             essentially call these methods in order.  The GetNext*Host()
  382. //             methods should be called repeatedly to get hosts for the input
  383. //             files of each type, one at a time.  Each host should be released
  384. //             as soon as it has received all its content.  The filenames are
  385. //             gathered during the parsing of the package file; litgen will
  386. //             choose the file ordering, and each host returned from the
  387. //             GetNext*Host() methods can be asked what file it is meant to
  388. //             receive.
  389. //
  390. //------------------------------------------------------------------------
  391.  
  392. [object, uuid(9EC81687-D4F9-4b20-969A-222BC00CE50A)]
  393. interface ILITWriter : IUnknown
  394. {
  395.     //+-----------------------------------------------------------------------
  396.     //
  397.     //  Function:       SetCallback
  398.     //  Description:    receives a pointer to a client-implemented callback interface
  399.     //  Parameters:     pCallback - the interface to receive text messages during
  400.     //                      content preparation
  401.     //  Returns:        S_OK
  402.     //                  E_INVALIDARG - pCallback is not an ILITCallback
  403.     //  Notes:          This call is optional.
  404.     //
  405.     //------------------------------------------------------------------------
  406.     HRESULT SetCallback([in] IUnknown* pCallback);
  407.     
  408.     //+-----------------------------------------------------------------------
  409.     //
  410.     //  Function:       Create
  411.     //  Description:    Create a new .LIT file.
  412.     //  Parameters:     pwszLitFile - the output filename
  413.     //                  pwszSourceBasePath - the base path to resolve relative
  414.     //                      links from
  415.     //                  pwszSource - DRM source (optional)
  416.     //                      free text, usually publisher or author name
  417.     //                  iMinimumReaderVersion - one of the following values:
  418.     //                      0 - run on all versions
  419.     //                      1 - run on all versions except the first Pocket PC
  420.     //                          ROM release
  421.     //  Returns:        S_OK
  422.     //                  E_INVALIDARG
  423.     //                  E_OUTOFMEMORY
  424.     //                  E_UNEXPECTED
  425.     //                  CO_E_NOTINITIALIZED
  426.     //                  E_FAIL
  427.     //  Notes:          iMinimumReaderVersion can be used to prevent older
  428.     //                  readers from attempting to open books that are known
  429.     //                  to render badly or cause other problems.  For example,
  430.     //                  the Pocket PC reader contained a much weaker CSS parser
  431.     //                  than more recent versions; some CSS constructs,
  432.     //                  particularly invalid CSS, could cause that version to
  433.     //                  fail completely.  As a result, LITGen will refuse to
  434.     //                  build a book containing such constructs, unless this
  435.     //                  value is 1 or above.
  436.     //
  437.     //------------------------------------------------------------------------
  438.     HRESULT Create([in, string] const wchar_t* pwszLitFile,
  439.                    [in, string] const wchar_t* pwszSourceBasePath,
  440.                    [in, string] const wchar_t* pwszSource,
  441.                    [in] int iMinimumReaderVersion);
  442.  
  443.     //+-----------------------------------------------------------------------
  444.     //
  445.     //  Function:       GetPackageHost
  446.     //  Description:    returns a parser host to receive the parsed package file
  447.     //  Parameters:     fEnforceOEB - whether errors should be thrown for non-OEB content
  448.     //                  ppHost - pointer to interface pointer of new host
  449.     //  Returns:        S_OK
  450.     //                  E_INVALIDARG
  451.     //                  E_OUTOFMEMORY
  452.     //                  E_UNEXPECTED
  453.     //                  E_FAIL
  454.     //  Notes:
  455.     //
  456.     //------------------------------------------------------------------------
  457.     HRESULT GetPackageHost([in] BOOL fEnforceOEB, [out, retval] IUnknown** ppHost);
  458.  
  459.     //+-----------------------------------------------------------------------
  460.     //
  461.     //  Function:       GetNextCSSHost
  462.     //  Description:    returns a CSS host to receive the stylesheet text
  463.     //  Parameters:     ppHost - pointer to interface pointer of new host
  464.     //  Returns:        S_OK
  465.     //                  S_FALSE - all CSS has been written, move on to content
  466.     //                  E_INVALIDARG
  467.     //                  E_OUTOFMEMORY
  468.     //                  E_UNEXPECTED - package file wasn't done
  469.     //                  E_FAIL
  470.     //  Notes:
  471.     //
  472.     //------------------------------------------------------------------------
  473.     HRESULT GetNextCSSHost([out, retval] IUnknown** ppHost);
  474.  
  475.     //+-----------------------------------------------------------------------
  476.     //
  477.     //  Function:       GetNextContentHost
  478.     //  Description:    returns a parser host to receive the parsed content file
  479.     //  Parameters:     ppHost - pointer to interface pointer of new host
  480.     //  Returns:        S_OK
  481.     //                  S_FALSE - all content has been written, move on to images
  482.     //                  E_INVALIDARG
  483.     //                  E_OUTOFMEMORY
  484.     //                  E_UNEXPECTED - not all CSS files were handled
  485.     //                  E_FAIL
  486.     //  Notes:
  487.     //
  488.     //------------------------------------------------------------------------
  489.     HRESULT GetNextContentHost([out, retval] IUnknown** ppHost);
  490.  
  491.     //+-----------------------------------------------------------------------
  492.     //
  493.     //  Function:       GetNextImageHost
  494.     //  Description:    returns an image host to receive the raw image file bytes
  495.     //  Parameters:     ppHost - pointer to interface pointer of new host
  496.     //  Returns:        S_OK
  497.     //                  S_FALSE - everything's been written.
  498.     //                  E_INVALIDARG
  499.     //                  E_OUTOFMEMORY
  500.     //                  E_UNEXPECTED - not all content files were handled
  501.     //                  E_FAIL
  502.     //  Notes:
  503.     //
  504.     //------------------------------------------------------------------------
  505.     HRESULT GetNextImageHost([out, retval] IUnknown** ppHost);
  506.  
  507.     //+-----------------------------------------------------------------------
  508.     //
  509.     //  Function:       Finish
  510.     //  Description:    Wraps and ties the finished file
  511.     //  Parameters:
  512.     //  Returns:        S_OK
  513.     //                  E_OUTOFMEMORY
  514.     //                  E_UNEXPECTED - not all input files were handled
  515.     //                  E_FAIL
  516.     //  Notes:          This must be called when all content has been written.
  517.     //
  518.     //------------------------------------------------------------------------
  519.     HRESULT Finish();
  520.  
  521.     //+-----------------------------------------------------------------------
  522.     //
  523.     //  Function:       Fail
  524.     //  Description:    Cleans up after a failure during content preparation
  525.     //  Parameters:
  526.     //  Returns:        S_OK
  527.     //  Notes:          Call this after any failure to abort and clean up.
  528.     //
  529.     //------------------------------------------------------------------------
  530.     HRESULT Fail();
  531. };
  532.  
  533. [
  534.     uuid(1450F9AF-3997-4fc6-B60C-973CAF37D729),
  535.     helpstring("LITGen Type Library"),
  536.     lcid(0x0409)
  537. ]
  538. library LITGen
  539. {
  540.     interface ILITCallback;
  541.     interface ILITTag;
  542.     interface ILITCSSHost;
  543.     interface ILITImageHost;
  544.     interface ILITWriter;
  545.     interface ILITParserHost;
  546. };
  547.