home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / yeah09.zip / YEAH.INF (.txt) < prev    next >
OS/2 Help File  |  1996-05-25  |  70KB  |  2,391 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About YEA.H ΓòÉΓòÉΓòÉ
  3.  
  4.  
  5. This reference introduce you to YEA.H, a C++ frame work for extended 
  6. attributes. 
  7.  
  8.       Introduction 
  9.       Licence agreement 
  10.       Trade marks 
  11.       Contacting the author 
  12.       Publishing EA classes 
  13.       Limitations 
  14.  
  15.  
  16. ΓòÉΓòÉΓòÉ 1.1. Introduction. ΓòÉΓòÉΓòÉ
  17.  
  18.  
  19. Introducing YEA.H - Your Extended Attribute Helper 
  20.  
  21. YEA.H is an Object Oriented C++ frame work making it simple for you to support 
  22. extended attributes in your software. 
  23.  
  24. YEA.H is designed to be: 
  25.  
  26.      Easy to use as a class library, to immediately gain support for some of 
  27.       the most frequently used extended attributes. 
  28.  
  29.      Easy to extend with new extended attributes, or make custom 
  30.       implementations for some of the supported attributes. 
  31.  
  32.  
  33. ΓòÉΓòÉΓòÉ 1.2. Licence agreement. ΓòÉΓòÉΓòÉ
  34.  
  35.  
  36. YEAH, its compiled library, source code, and documentation, is licensed to you 
  37. under the following license agreement. Use or distribution of YEAH constitutes 
  38. your acceptance of that agreement. 
  39.  
  40. YEAH, the compiled library, source code and, documentation, is the copyrighted 
  41. material of Bj╨ñrn Fahller. 
  42.  
  43. Under this licence, you may: 
  44.  
  45.    1. Redistribute YEAH in any way for and shape, suitable to you as long as 
  46.       the original contents remain unchanged and that the redistribution is 
  47.       free (fees to cover media and transfer costs are allowed.) 
  48.  
  49.    2. Use YEAH, in your applications, be they free, shareware, educational or 
  50.       commercial. 
  51.  
  52.    3. Write and publish additional classes to YEAH, as long as those additional 
  53.       classes are published with the same licence constraints as YEAH. 
  54.  
  55.    4. Make proprietary changes to YEAH, provided you do not redistribute YEAH 
  56.       with those changes. 
  57.  
  58.  Warranty 
  59.  
  60.  BECAUSE YEAH IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, 
  61.  TO THE EXTENT PERMITTED BY LAW. USE YEAH AT YOUR OWN RISK. 
  62.  
  63.  IN NO EVENT SHALL BJ╨⌐RN FAHLLER BE HELD LIABLE FOR ANY DAMAGE DUE TO THE USE, 
  64.  ABUSE, OR INABILITY TO USE, YEAH. 
  65.  
  66.  
  67. ΓòÉΓòÉΓòÉ 1.3. Trade Marks. ΓòÉΓòÉΓòÉ
  68.  
  69.  
  70. IBM, Visual Age C++ and Open Class Library are registered trade marks of 
  71. International Business Machines Inc. 
  72.  
  73. C++ is (I think) a registered trademark of Unix Systems Laboratories. 
  74.  
  75.  
  76. ΓòÉΓòÉΓòÉ 1.4. Contacting the Author. ΓòÉΓòÉΓòÉ
  77.  
  78.  
  79. If you have questions, suggestions, want to report bugs, include new classes in 
  80. the base package, or for other reasons would like to get in youch with Bj╨ñrn 
  81. Fahller, he can be reached in the following ways: 
  82.  
  83.  E-mail:   bjorn@algonet.se 
  84.  
  85.  Mail:     Bj╨ñrn Fahller 
  86.            Siljansv╨ögen 35 
  87.            S-120 55 ╨ƒrsta 
  88.            SWEDEN. 
  89.  
  90.  Phone:    +46 8 918297 (evenings CET) 
  91.  
  92.  Fax:      +46 8 918297 (daytime CET) 
  93.  
  94.  The newsgroup comp.os.os2.programmer.oop will also be monitored for 
  95.  discussions regarding YEA.H, but my newsfeed is very slow, often lagging up to 
  96.  a week, so this is most probably not the best way to get quick responses. 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 1.5. Publishing EA classes. ΓòÉΓòÉΓòÉ
  100.  
  101.  
  102. If you want to publish concrete extended attribute classes based on YEA.H, you 
  103. have 3 choises within the licence agreement. 
  104.  
  105.    1. Publish the class on your own, with the same licence constraints as 
  106.       YEA.H, i.e. free of charge and with source code. 
  107.  
  108.    2. Publish it as a "contribution" to YEA.H. Future releases of YEA.H will 
  109.       have a "contrib" subdirectory, with such classes. You will be the 
  110.       copyright holder for such a contribution, hold the full responsibility 
  111.       for it, document it as you please. The compiled library file, or object 
  112.       file, will be your responsibility too, and it will not be a part of 
  113.       YEAH.LIB. 
  114.  
  115.    3. Publish it as a part of YEAH. The difference between this and the 
  116.       previous, is that the compiled object file will be included in YEAH.LIB, 
  117.       that the documentation will be included in future versions of YEAH.INF, 
  118.       that I want to have a say about the way the class is shaped. You still 
  119.       remain the copyright holder, and hold the full responsibility for your 
  120.       classes. 
  121.  
  122.       If you have plans for such a class, or a set of such classes, please 
  123.       contact me and tell me of your plans. If some one else is also working on 
  124.       a similar class, I will introduce you to each other, so that you may 
  125.       share ideas and, if you so wish, cooperate. 
  126.  
  127.  For the latter kind, I would specifically like to see an icon class, and a C++ 
  128.  stream based binary class. Bitmap and metafile extended attribute classes 
  129.  would be most welcome too. 
  130.  
  131.  
  132. ΓòÉΓòÉΓòÉ 1.6. Limitations. ΓòÉΓòÉΓòÉ
  133.  
  134.  
  135. YEA.H can currently only be used with IBM Visual Age C++, since it makes use of 
  136. a Visual Age C++ specific #pragma directive ( #pragma 
  137. define(IKeySortedSet<EA::Name, IString>)), which expands the template, 
  138. regardless of whether it is used in your application or not. Not doing this 
  139. results in a link error. In the future, this will be removed, since the C++ 
  140. construct IKeySortedSet<EA::Name, IString>; is defined by the proposed ANSI/ISO 
  141. C++ standard to expand the template. 
  142.  
  143. As can be seen, it also makes use of classes IKeySortedSet and IString, which 
  144. are part of IBM Open Class Library. Once enough parts of the proposed ANSI/ISO 
  145. C++ standard are commonplace in compilers, a compiler independent version will 
  146. be written, since the ANSI/ISO C++ standard will include the necessary 
  147. collection classes and a string class. 
  148.  
  149.  
  150. ΓòÉΓòÉΓòÉ 2. Classes ΓòÉΓòÉΓòÉ
  151.  
  152.  
  153. These are the classes available in version 0.9 of YEA.H 
  154.  
  155.       EA. 
  156.       StringEA. 
  157.       MTSequenceEA. 
  158.       TSequenceEA<T>. 
  159.       TEA<T, EA::Identifier>. 
  160.       SequenceEA. 
  161.  
  162.  
  163. ΓòÉΓòÉΓòÉ 2.1. EA. ΓòÉΓòÉΓòÉ
  164.  
  165.  
  166. EA, Extended Attribute base class. 
  167.  
  168.       Description. 
  169.       Derivation. 
  170.       Public Interface. 
  171.       Protected Interface. 
  172.  
  173.  
  174. ΓòÉΓòÉΓòÉ <hidden> EA - Description. ΓòÉΓòÉΓòÉ
  175.  
  176.  
  177. EA is the base class for all extended attributes. Most of the use of EA 
  178. directly is through the many static functions for handling extended attributes 
  179. in general. Most use of EA, however, will be indirectly, through objects of 
  180. other classes, implementing concrete extended attributes. 
  181.  
  182.  
  183. ΓòÉΓòÉΓòÉ <hidden> EA - Derivation. ΓòÉΓòÉΓòÉ
  184.  
  185.  
  186. Inherits: 
  187.  
  188.       none. 
  189.  
  190.   Inherited by: 
  191.  
  192.       StringEA (through TEA<StringEA,EAT_ASCII>) 
  193.  
  194.       MTSequenceEA (through TEA<MTSequenceEA, EAT_MVMT>) 
  195.  
  196.       TSequenceEA<T> (through TEA<SequenceEA, EAT_MVST> and SequenceEA) 
  197.  
  198.  
  199. ΓòÉΓòÉΓòÉ <hidden> EA - Public Interface. ΓòÉΓòÉΓòÉ
  200.  
  201.  
  202. Nested types: 
  203.  
  204.       Identifier 
  205.       Creator 
  206.       CreatorIdPair 
  207.       CreatorMap 
  208.       Flagset 
  209.       Name 
  210.       NameSet 
  211.       Error 
  212.       ErrorHandler 
  213.  
  214.  Static Public Data. 
  215.  
  216.       defaultCreatorMap 
  217.       errorHandler 
  218.  
  219.  Static Public Functions. 
  220.  
  221.       namesIn 
  222.       newFrom 
  223.       remove 
  224.  
  225.  Public Instance Functions. 
  226.  
  227.       Destructor 
  228.       attributeId 
  229.       getFlags 
  230.       setFlags 
  231.       getFrom 
  232.       storeTo 
  233.       clone 
  234.       setCreatorMap 
  235.  
  236.  
  237. ΓòÉΓòÉΓòÉ <hidden> EA - Protected Interface. ΓòÉΓòÉΓòÉ
  238.  
  239.  
  240. Static Protected Functions. 
  241.  
  242.       read 
  243.       write 
  244.  
  245.  Instance Protected Functions. 
  246.  
  247.       Constructors 
  248.       Assignment Operator 
  249.       readFrom 
  250.       writeTo 
  251.  
  252.  
  253. ΓòÉΓòÉΓòÉ 2.2. StringEA. ΓòÉΓòÉΓòÉ
  254.  
  255.  
  256. StringEA, String extended attribute (EAT_ASCII). 
  257.  
  258.       Description. 
  259.       Derivation. 
  260.       Public Interface. 
  261.       Protected Interface. 
  262.  
  263.  
  264. ΓòÉΓòÉΓòÉ <hidden> StringEA - Description. ΓòÉΓòÉΓòÉ
  265.  
  266.  
  267. StringEA represents ASCII string extended attributes used, for example, in the 
  268. .SUBJECT and .LONGNAME attributes supported by the WPS. To make StringEA easy 
  269. to use, it inherits IString, and provides the full functionality of IString in 
  270. addition, of course, to being an extended attribute that can be read and 
  271. written to files. 
  272.  
  273. StringEA implements the EAT_ASCII extended attribute. 
  274.  
  275.  
  276. ΓòÉΓòÉΓòÉ <hidden> StringEA - Derivation. ΓòÉΓòÉΓòÉ
  277.  
  278.  
  279. StringEA is multiply inherited with IString, to provide full string 
  280. functionality for the extended attribute. 
  281.  
  282.  
  283. ΓòÉΓòÉΓòÉ <hidden> StringEA - Public Interface. ΓòÉΓòÉΓòÉ
  284.  
  285.  
  286. Public Instance Functions 
  287.  
  288.       Constructors 
  289.       Assignment Operator 
  290.       clone 
  291.  
  292.   Inherited Public Instance Functions. 
  293.  
  294.    From EA 
  295.  
  296.       attributeId 
  297.       getFlags 
  298.       setFlags 
  299.       getFrom 
  300.       storeTo 
  301.       setCreatorMap 
  302.  
  303.  Public Static Functions 
  304.  
  305.       - 
  306.  
  307.   Inherited Public Static Functions. 
  308.  
  309.    From TEA<StringEA, EAT_ASCII> 
  310.  
  311.       cast 
  312.       allowDynamic 
  313.       disallowDynamic 
  314.  
  315.  Class Constants 
  316.  
  317.       - 
  318.   Inherited Class Constants 
  319.  
  320.    From TEA<StringEA, EAT_ASCII> 
  321.  
  322.       id 
  323.  
  324.  
  325. ΓòÉΓòÉΓòÉ <hidden> StringEA - Protected Interface. ΓòÉΓòÉΓòÉ
  326.  
  327.  
  328. Protected Instance Functions 
  329.  
  330.       readFrom 
  331.       writeTo 
  332.  
  333.  Inherited Protected Instance Functions 
  334.  
  335.       - 
  336.  Protected Static Functions 
  337.  
  338.       - 
  339.  Inherited Protected Static Functions 
  340.  
  341.       - 
  342.  
  343.  
  344. ΓòÉΓòÉΓòÉ 2.3. MTSequenceEA. ΓòÉΓòÉΓòÉ
  345.  
  346.  
  347. MTSequenceEA, Multi Type sequence extended attribute (EAT_MVMT). 
  348.  
  349.       Description. 
  350.       Derivation. 
  351.       Public Interface. 
  352.       Protected Interface. 
  353.  
  354.  
  355. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA - Description. ΓòÉΓòÉΓòÉ
  356.  
  357.  
  358. MTSequenceEA represents multi value multi type extended attributes; an extended 
  359. attribute that is a sequence of other extended attributes. There is no 
  360. restriction on the types of the contained extended attributes. 
  361.  
  362. MTSequenceEA is, for example, used for the .KEYPHRASES, .TYPES and .ASSOCTABLE 
  363. extended attributes, supported by the WPS. 
  364.  
  365. To make MTSequenceEA offer powerful sequence manipulation, yet stay simple to 
  366. use and consistent with the other sequences in your application, it inherits 
  367. ISequence<EA*>. 
  368.  
  369. MTSequenceEA implements the EAT_MVMT extended attribute. 
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA - Derivation. ΓòÉΓòÉΓòÉ
  373.  
  374.  
  375. MTSequenceEA multiply inherits ISequence, to provide strong sequence 
  376. manipulation that is easy to use and consistent with the rest of your 
  377. application. 
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA - Public Interface. ΓòÉΓòÉΓòÉ
  381.  
  382.  
  383. Nested Types 
  384.  
  385.       ErrorFunction 
  386.  
  387.  Public Instance Data 
  388.  
  389.       pCreatorMap 
  390.  
  391.  Public Static Data 
  392.  
  393.       errorFunction 
  394.  
  395.  Public Instance Functions 
  396.  
  397.       Constructors 
  398.       Destructor 
  399.       Assignment Operator 
  400.       clone 
  401.       setCreatorMap 
  402.       getCodePage 
  403.       setCodePage 
  404.  
  405.   Inherited Instance Public Functions. 
  406.  
  407.    From EA 
  408.  
  409.       attributeId 
  410.       getFlags 
  411.       setFlags 
  412.       getFrom 
  413.       storeTo 
  414.  
  415.  Public Static Functions 
  416.  
  417.       - 
  418.  
  419.   Inherited Public Static Functions. 
  420.  
  421.    From TEA<MTSequenceEA, EAT_MVMT> 
  422.  
  423.       cast 
  424.       allowDynamic 
  425.       disallowDynamic 
  426.  
  427.  Class Constants 
  428.  
  429.       - 
  430.   Inherited Class Constants 
  431.  
  432.    From TEA<MTSequenceEA, EAT_MVMT> 
  433.  
  434.       id 
  435.  
  436.  
  437. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA - Protected Interface. ΓòÉΓòÉΓòÉ
  438.  
  439.  
  440. Protected Instance Functions 
  441.  
  442.       readFrom 
  443.       writeTo 
  444.  
  445.  Inherited Protected Instance Functions 
  446.  
  447.       - 
  448.  
  449.  Protected Static Functions 
  450.  
  451.       - 
  452.  
  453.  Inherited Protected Static Functions 
  454.  
  455.       - 
  456.  
  457.  
  458. ΓòÉΓòÉΓòÉ 2.4. TSequenceEA<T>. ΓòÉΓòÉΓòÉ
  459.  
  460.  
  461. TSequenceEA<T>, Typed sequence extended attribute (EAT_MVST). 
  462.  
  463.       Description. 
  464.       Derivation. 
  465.       Public Interface. 
  466.       Protected Interface. 
  467.  
  468.  
  469. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T> - Description. ΓòÉΓòÉΓòÉ
  470.  
  471.  
  472. TSequenceEA<T> represents sequences of extended attributes with a common type; 
  473. in essense, a typed array of extended attributes. TSequenceEA<T> is 
  474. surpricingly uncommon in OS/2. Even though it could be used for attributes like 
  475. .KEYPHRASES and .TYPES, they are not. 
  476.  
  477. T must be an extended attribute class itself, such as StringEA. 
  478.  
  479. IBM Work Frame makes use of string type, typed extended attribute sequences, 
  480. for storing build support information for make files. 
  481.  
  482. TSequenceEA<T> implements the EAT_MVST extended attribute. 
  483.  
  484.  
  485. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T> - Derivation. ΓòÉΓòÉΓòÉ
  486.  
  487.  
  488. TSequenceEA multiply inherits ISequence, to provide strong and simple sequence 
  489. manipulation that is consistent with the rest of your application. 
  490.  
  491.  
  492. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T> - Public Interface. ΓòÉΓòÉΓòÉ
  493.  
  494.  
  495. Public Instance Functions 
  496.  
  497.       Constructors 
  498.       Assignment Operator 
  499.       Destructor 
  500.       clone 
  501.  
  502.   Inherited Public Instance Functions. 
  503.  
  504.    From SequenceEA 
  505.  
  506.       getCodePage 
  507.       setCodePage 
  508.       contentId 
  509.       setCreatorMap 
  510.  
  511.    From EA 
  512.  
  513.       attributeId 
  514.       getFlags 
  515.       setFlags 
  516.       getFrom 
  517.       storeTo 
  518.  
  519.  Static Public Functions. 
  520.  
  521.       allowDynamic 
  522.       disallowDynamic 
  523.       cast 
  524.  
  525.  Class Constants. 
  526.  
  527.       elementId 
  528.  
  529.  
  530. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T> - Protected Interface. ΓòÉΓòÉΓòÉ
  531.  
  532.  
  533. Protected Instance Functions 
  534.  
  535.       readFrom 
  536.       writeTo 
  537.  
  538.  Inherited Protected Instance Functions 
  539.  
  540.       - 
  541.  Protected Static Functions 
  542.  
  543.       - 
  544.  Inherited Protected Static Functions 
  545.  
  546.       - 
  547.  
  548.  
  549. ΓòÉΓòÉΓòÉ 2.5. TEA<T, EA::Identifier>. ΓòÉΓòÉΓòÉ
  550.  
  551.  
  552.       Description. 
  553.       Derivation. 
  554.       Public Interface. 
  555.       Protected Interface. 
  556.  
  557.  
  558. ΓòÉΓòÉΓòÉ <hidden> TEA<T, EA::Identifier> - Description. ΓòÉΓòÉΓòÉ
  559.  
  560.  
  561. TEA<T, EA::Identifier> - Intermediate class, providing base functionality for 
  562. its descendants. You never use this class as is, but it provides a consistent 
  563. and safe interface to its descendants, at the same time as it saves time for 
  564. developers of descendants and reduce the risk for errors by removing unecessary 
  565. code duplication. 
  566.  
  567. TEA<T,EA::Identifier> hides the static member functions namesIn, newFrom and 
  568. remove from EA, since their use from any class other than directly from EA, 
  569. would be confusing. EA::newFrom, for example, can return any kind of extended 
  570. attribute object. If newFrom would be publically available to all descendants 
  571. of EA, a call to StringEA::newFrom, for example, would be legal, but is in no 
  572. way guaranteed to return a StringEA object. To avoid the confusion that would 
  573. arise was the above allowed, the functions are declared private in 
  574. TEA<T,EA::Identifier>. 
  575.  
  576. For the same reason, the types Creator, CreatorMap, CreatorIdPair, Name,Error, 
  577. ErrorHandler, Flagset, Identifier and NameSet are hidden by TEA and must be 
  578. explicitly qualified with EA:: scope when used. 
  579.  
  580.  
  581. ΓòÉΓòÉΓòÉ <hidden> TEA<T, EA::Identifier> - Derivation. ΓòÉΓòÉΓòÉ
  582.  
  583.  
  584. Inherits. 
  585.  
  586.  EA 
  587.  
  588. Inherited by: 
  589.  
  590.       StringEA 
  591.       MTSequenceEA 
  592.       SequenceEA 
  593.  
  594.  
  595. ΓòÉΓòÉΓòÉ <hidden> TEA<T, EA::Identifier> - Public Interface. ΓòÉΓòÉΓòÉ
  596.  
  597.  
  598. Class constants 
  599.  
  600.       id 
  601.  
  602.  Public Instance Methods 
  603.  
  604.       Destructor 
  605.  
  606.  Public Static Methods 
  607.  
  608.       cast 
  609.       allowDynamic 
  610.       disallowDynamic 
  611.  
  612.  
  613. ΓòÉΓòÉΓòÉ <hidden> TEA<T, EA::Identifier> - Protected Interface. ΓòÉΓòÉΓòÉ
  614.  
  615.  
  616. Protected Instance Methods 
  617.  
  618.       Constructors 
  619.       Assignment Operator 
  620.  
  621.  
  622. ΓòÉΓòÉΓòÉ 2.6. SequenceEA. ΓòÉΓòÉΓòÉ
  623.  
  624.  
  625.       Description. 
  626.       Derivation. 
  627.       Public Interface. 
  628.       Protected Interface. 
  629.  
  630.  
  631. ΓòÉΓòÉΓòÉ <hidden> SequenceEA - Description. ΓòÉΓòÉΓòÉ
  632.  
  633.  
  634. SequenceEA - Intermediate class, providing common base functionality for 
  635. TSequenceEA<T>. 
  636.  
  637. You should never work directly towards this class, but always towards 
  638. TSequenceEA<T>. If you want to write your own implementation of typed sequecene 
  639. extended attributes, SequenceEA can be a good class to inherit from. 
  640.  
  641.  
  642. ΓòÉΓòÉΓòÉ <hidden> SequenceEA - Derivation. ΓòÉΓòÉΓòÉ
  643.  
  644.  
  645. Inherits: 
  646.  
  647.       EA 
  648.  
  649.       TEA<SequenceEA, EAT_MVST> 
  650.  
  651.  Inherited by: 
  652.  
  653.       TSequenceEA<T> 
  654.  
  655.  
  656. ΓòÉΓòÉΓòÉ <hidden> SequenceEA - Public Interface. ΓòÉΓòÉΓòÉ
  657.  
  658.  
  659. Static Public Data. 
  660.  
  661.       errorFunction 
  662.  
  663.  Instance Public Functions. 
  664.  
  665.       Destructor 
  666.       getCodePage 
  667.       setCodePage 
  668.       contentId 
  669.       clone 
  670.       setCreatorMap 
  671.  
  672.  
  673. ΓòÉΓòÉΓòÉ <hidden> SequenceEA - Protected Interface. ΓòÉΓòÉΓòÉ
  674.  
  675.  
  676. Instance Protected Functions. 
  677.  
  678.       Constructors 
  679.       Assignment Operator 
  680.       writeTo 
  681.       readFrom 
  682.  
  683.  Instance Protected Data. 
  684.  
  685.       pCreatorMap 
  686.  
  687.  Static Protected Functions. 
  688.  
  689.       allowDynamic 
  690.  
  691.  
  692. ΓòÉΓòÉΓòÉ <hidden> EA::Identifier ΓòÉΓòÉΓòÉ
  693.  
  694.  
  695. typedef unsigned short Identifier; 
  696.  
  697. Identifies the type of an extended attribute. Values supported by: 
  698.  
  699.  OS/2 are:           YEA.H are: 
  700.  EAT_BINARY 
  701.  EAT_ASCII           StringEA::id 
  702.  EAT_BITMAP 
  703.  EAT_METAFILE 
  704.  EAT_EA 
  705.  EAT_MVMT            MTSequenceEA::id 
  706.  EAT_MVST            TSequenceEA<T>::id 
  707.  EAT_ASN1 
  708.  
  709.  
  710. ΓòÉΓòÉΓòÉ <hidden> EA::Creator ΓòÉΓòÉΓòÉ
  711.  
  712.  
  713. typedef EA* (*Creator)(istrstream&, EA::CreatorMap*); 
  714.  
  715. Defines a pointer to a function that creates an extended attribute object. For 
  716. the specific attributes, such functions are defined by the private static 
  717. member function  TEA<T,EA::Identifier>::createFrom 
  718.  
  719. If you write your own creator function, it should read as far into the stream 
  720. as is needed to know the type of the object to create, and then create the 
  721. object on the heap. It should not read a value into the object, though. 
  722.  
  723.  
  724. ΓòÉΓòÉΓòÉ <hidden> EA::CreatorIdPair ΓòÉΓòÉΓòÉ
  725.  
  726.  
  727. struct CreatorIdPair { 
  728.  EA::Creator c; 
  729.  EA::Identifier id; 
  730.  IMngPointer<EA::CreatorMap> pSubMap; 
  731. } 
  732.  
  733. Struct matching an EA::Identifier with an EA::Creator function. Used internally 
  734. by the EA::newFrom functions, and by multi value extended attributes. 
  735.  
  736. The c part is the function that will create new objects on the heap if the 
  737. element found matches that of id. pSubMap is the map passed to the creator 
  738. function, which is useful for typed collections, since the creator function 
  739. will then use that map to create its containing elements. 
  740.  
  741. For flat (non-collection extended attributes) pSubMap is 0. 
  742.  
  743.  
  744. ΓòÉΓòÉΓòÉ <hidden> EA::CreatorMap ΓòÉΓòÉΓòÉ
  745.  
  746.  
  747. typedef IMap<EA::CreatorIdPair, EA::Identifier> CreatorMap; 
  748.  
  749. Container of EA::CreatorIdPair for use internally by the creator functions, and 
  750. multi value extended attributes. 
  751.  
  752.  
  753. ΓòÉΓòÉΓòÉ <hidden> EA::Flagset ΓòÉΓòÉΓòÉ
  754.  
  755.  
  756. typedef enum { optional = 0, mandatory = 0x80 } Flagset; 
  757.  
  758. Flag used for telling whether an extended attribute is needed (i.e. must not be 
  759. discarded,) or not. The only legal values are: 
  760.  
  761.   0x00 (optional)     The extended attribute is not needed. 
  762.   0x80 (mandatory)    The extended attribute is needed. 
  763.  
  764.  
  765. ΓòÉΓòÉΓòÉ <hidden> EA::Name ΓòÉΓòÉΓòÉ
  766.  
  767.  
  768.  struct Name { 
  769.   IString name; 
  770.   EA::Flagset flags; 
  771.  }; 
  772.  
  773. Description of an extended attribute for a file. A file can be queried for what 
  774. extended attributes it has, by calling one of the EA::namesIn methods, which 
  775. returns the set of names as an EA::NameSet, which elements are of type 
  776. EA::Name. 
  777.  
  778.  
  779. ΓòÉΓòÉΓòÉ <hidden> EA::NameSet ΓòÉΓòÉΓòÉ
  780.  
  781.  
  782. typedef IKeySortedSet<EA::Name,IString> NameSet; 
  783.  
  784. Set of extended attributes. This is the return value from the EA::namesIn 
  785. functions. 
  786.  
  787.  
  788. ΓòÉΓòÉΓòÉ <hidden> EA::Error ΓòÉΓòÉΓòÉ
  789.  
  790.  
  791.  typedef enum { 
  792.   ReadError, 
  793.   WriteError, 
  794.   NoSuchEAError, 
  795.   TypeMismatchError 
  796.  } Error; 
  797.  
  798. The different kinds of errors that can occur within YEA.H. The errors codes are 
  799. used as follows: 
  800.  
  801.  Error                  Situation/Meaning 
  802.  
  803.  ReadError              The extended attribute could not be read. Issued if the 
  804.                         file to read from does not exist, or is not readable. 
  805.                         The accompanying code sent to the error handler 
  806.                         function will be the OS/2 error code. 
  807.  
  808.  WriteError             The extended attribute could not be written. Issued if 
  809.                         the file to write to does not exist, is write 
  810.                         protected, the extended attribute name was illegal, or 
  811.                         the total size of the extended attribute exceeded the 
  812.                         64Kb limit. The accompanying code sent to the error 
  813.                         handler function will be the OS/2 error code. 
  814.  
  815.  NoSuchEAError          An attempt was made to read an extended attribute with 
  816.                         a name that is not defined for the specified file. The 
  817.                         accompanying code sent to the error handler function 
  818.                         will be 0. 
  819.  
  820.  TypeMismatchError      An attempt was made to read an extended attribute of a 
  821.                         specific type, and the attribute read had another type. 
  822.                         The accompanying code sent to te error handler function 
  823.                         will be the type identifier of the attribute read. 
  824.  
  825.  
  826. ΓòÉΓòÉΓòÉ <hidden> EA::ErrorHandler ΓòÉΓòÉΓòÉ
  827.  
  828.  
  829. typedef void (*ErrorHandler)(EA::Error, unsigned long); 
  830.  
  831. Type of the error handler function. 
  832.  
  833.  
  834. ΓòÉΓòÉΓòÉ <hidden> EA::defaultCreatorMap ΓòÉΓòÉΓòÉ
  835.  
  836.  
  837. public: 
  838.  static EA::CreatorMap defaultCreatorMap; 
  839.  
  840. The CreatorMap that will be used for creating extended attribute objects with 
  841. the getFrom and newFrom functions, unless otherwise specified. 
  842.  
  843.  
  844. ΓòÉΓòÉΓòÉ <hidden> EA::errorHandler ΓòÉΓòÉΓòÉ
  845.  
  846.  
  847. public: 
  848.  static EA::ErrorHandler errorHandler; 
  849.  
  850. The ErrorHandler to call when error situations arise. To set your own error 
  851. handler, simply set this pointer to your own function. 
  852.  
  853. The default error handler throws exceptions: 
  854.  
  855.  Error                    Exception thrown 
  856.  
  857.  EA::ReadError            EAReadError("Failed to read EA") with the error code 
  858.                           given by OS/2 as its errorId. 
  859.  
  860.  EA::WriteError           EAWriteError("Failed to write EA") with the error 
  861.                           code given by OS/2 as its errorId. 
  862.  
  863.  EA::NoSuchEAError        EATypeMismatchError("Unknown EA type") with the 
  864.                           errorId set to 0. 
  865.  
  866.  EA::TypeMismatchError    EATypeMismatchError("Unexpected EA type") with the 
  867.                           type identifier as the errorId. 
  868.  
  869.  Others.                  EAError("unknown error"); 
  870.  
  871.  
  872. ΓòÉΓòÉΓòÉ <hidden> EA::namesIn ΓòÉΓòÉΓòÉ
  873.  
  874.  
  875. public: 
  876.  static EA::NameSet namesIn(const IString& file); 
  877.  static EA::NameSet namesIn(fstreambase& file); 
  878.  
  879. Get the names for the set of extended attributes defined for the file pointed 
  880. to by file. 
  881.  
  882. Possible errors are: 
  883.  
  884.  Error               Action 
  885.  EA::ReadError       EA::errorHandler called with EA::ReadError and the error 
  886.                      code given by OS/2. If errorHandler returns, the set 
  887.                      returned by namesIn will be empty. 
  888.  
  889.  
  890. ΓòÉΓòÉΓòÉ <hidden> EA::newFrom ΓòÉΓòÉΓòÉ
  891.  
  892.  
  893. public: 
  894.  static EA* newFrom(const IString& file, 
  895.            const IString& name, 
  896.            const EA::CreatorMap& = EA::defaultCreatorMap); 
  897.  
  898.  static EA* newFrom(fstreambase& file, 
  899.            const IString& name, 
  900.            const EA::CreatorMap& = EA::defaultCreatorMap); 
  901.  
  902. Create a new extended attribute object on the heap. The type will be decided 
  903. when reading the extended attribute, and the object to create will be decided 
  904. by looking up the creator map passed. 
  905.  
  906. Note:  To create an object of a class by calling newFrom, the static method 
  907.        allowDynamic must haven been called for the class on the creator map 
  908.        passed. If allowDynamic has not been called, 0 will be returned. 
  909.  
  910.  Possible errors are: 
  911.  
  912.  Error                    Action 
  913.  
  914.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  915.                           error code returned by OS/2. EA::errorHandler 
  916.                           returns, newFrom returns 0. 
  917.  
  918.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  919.                           If EA::errorHandler returns, newFrom returns 0. 
  920.  
  921.  Note:  In addition to the above, the extended attribute object created can 
  922.         find and report errors of its own. What errors they are, and how they 
  923.         are handled, depends on the type of extended attribute object being 
  924.         created. 
  925.  
  926.  
  927. ΓòÉΓòÉΓòÉ <hidden> EA::remove ΓòÉΓòÉΓòÉ
  928.  
  929.  
  930. public: 
  931.  static void remove(const IString& file, 
  932.            const IString& name); 
  933.  
  934.  static void remove(fstreambase& file, 
  935.            const IString& name); 
  936.  
  937. Remove the extended attribute pointed to by name from the file. After 
  938. execution, there will be no extended attribute by the specified name on the 
  939. file, unless an error occurs. 
  940.  
  941. Possible errors are: 
  942.  
  943.  Error               Action 
  944.  
  945.  EA::WriteError      Call EA::errorHandler with EA::WriteError and the error 
  946.                      code returned by OS/2. 
  947.  
  948.  
  949. ΓòÉΓòÉΓòÉ <hidden> virtual EA::~EA(void) ΓòÉΓòÉΓòÉ
  950.  
  951.  
  952. public: 
  953.  virtual ~EA(void); 
  954.  
  955. Destroy an extended attribute. 
  956.  
  957.  
  958. ΓòÉΓòÉΓòÉ <hidden> EA::attributeId ΓòÉΓòÉΓòÉ
  959.  
  960.  
  961. public: 
  962.  EA::Identifier attributeId(void) const; 
  963.  
  964. Get the attribute identifier of the extended attribute object. 
  965.  
  966. Possible errors are: 
  967.  
  968.       - 
  969.  
  970.  
  971. ΓòÉΓòÉΓòÉ <hidden> virtual EA::getFlags ΓòÉΓòÉΓòÉ
  972.  
  973.  
  974. public: 
  975.  EA::Flagset getFlags(void) const; 
  976.  
  977. Get the flags for the current object. 
  978.  
  979. Possible errors are: 
  980.  
  981.       - 
  982.  
  983.  
  984. ΓòÉΓòÉΓòÉ <hidden> virtual EA::setFlags ΓòÉΓòÉΓòÉ
  985.  
  986.  
  987. public: 
  988.  void setFlags(EA::Flagset); 
  989.  
  990. Set the flags for the current object. 
  991.  
  992. Possible errors are: 
  993.  
  994.       - 
  995.  
  996.  
  997. ΓòÉΓòÉΓòÉ <hidden> EA::getFrom ΓòÉΓòÉΓòÉ
  998.  
  999.  
  1000. public: 
  1001.  void getFrom(const IString& file, 
  1002.         const IString& name); 
  1003.  
  1004.  void getFrom(fstreambase& file, 
  1005.         const IString& name); 
  1006.  
  1007. Give the extended attribute object a new value by assigning it the value read 
  1008. from the named extended attribute. 
  1009.  
  1010. Possible errors are: 
  1011.  
  1012.  Error                    Action 
  1013.  
  1014.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1015.                           error code returned by OS/2. The extended attribute 
  1016.                           object itself not be changed. 
  1017.  
  1018.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1019.                           The extended attribute object itself will not be 
  1020.                           changed. 
  1021.  
  1022.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1023.                           the type found. The extended attribute object itself 
  1024.                           will not be changed. 
  1025.  
  1026.  Note:  If the extended attribute object is a collection extended attribute, 
  1027.         the containing parts may themselves find and report other errors. What 
  1028.         kind they are of, and how they are reported, depends on the type. 
  1029.  
  1030.  
  1031. ΓòÉΓòÉΓòÉ <hidden> EA::storeTo ΓòÉΓòÉΓòÉ
  1032.  
  1033.  
  1034. public: 
  1035.  void storeTo(const IString& file, 
  1036.         const IString& name); 
  1037.  
  1038.  void storeTo(fstreambase& file, 
  1039.         const IString& name); 
  1040.  
  1041. Store the value of the extended attribute to the file, using the name given. 
  1042.  
  1043. Possible errors are: 
  1044.  
  1045.  Error                    Action 
  1046.  
  1047.  EA::WriteError           Call EA::errorHandler with EA::WriteError and the 
  1048.                           error code returned by OS/2. 
  1049.  
  1050.  
  1051. ΓòÉΓòÉΓòÉ <hidden> EA::clone ΓòÉΓòÉΓòÉ
  1052.  
  1053.  
  1054. public: 
  1055.  virtual EA* clone(void) const = 0; 
  1056.  
  1057. Create an exact deep copy of self. Must be overridden by all descendant 
  1058. classes. Used by the copy constructors and assignment operators of extended 
  1059. attribute collection classes such as MTSequenceEA and TSequenceEA<T> to provide 
  1060. for deep copying. 
  1061.  
  1062. To work properly with typed collection extended attributes, like TSequenceEA<T> 
  1063. the return type must be overridden. The return type for a class C, derived in 
  1064. one or several generations from EA, must be C*. 
  1065.  
  1066. clone will normally not find or report errors, but it depends on the actual 
  1067. extended attribute class if errors can occur, and how they are reported. 
  1068.  
  1069.  
  1070. ΓòÉΓòÉΓòÉ <hidden> EA::setCreatorMap ΓòÉΓòÉΓòÉ
  1071.  
  1072.  
  1073. public: 
  1074.  virtual void setCreatorMap(const EA::CreatorMap*) 
  1075.  
  1076. This default implementation of setCreatorMap does nothing at all. Collection 
  1077. classes should override it and create their children from the creator map 
  1078. passed. 
  1079.  
  1080. Possible errors are: 
  1081.  
  1082.       - 
  1083.  
  1084.  
  1085. ΓòÉΓòÉΓòÉ <hidden> EA::read ΓòÉΓòÉΓòÉ
  1086.  
  1087.  
  1088. protected: 
  1089.  static istrstream& read(EA* pea, istrstream& is) 
  1090.  
  1091. Calls pea->readFrom(is), a way to access the protected method of a sibling. Use 
  1092. when implementing multi value extended attributes, to read a value into one of 
  1093. the attributes contained. 
  1094.  
  1095. read will normally not find or report errors, but it depends on the actual 
  1096. extended attribute class if errors can occur, and how they are reported. 
  1097. Objects of collection extended attribute classes, like MTSequenceEA and 
  1098. TSequenceEA<T> might well find and report errors. 
  1099.  
  1100.  
  1101. ΓòÉΓòÉΓòÉ <hidden> EA::write ΓòÉΓòÉΓòÉ
  1102.  
  1103.  
  1104. protected: 
  1105.  static ostrstream& write(EA* pea, ostrstream& os) 
  1106.  
  1107. Calls pea->writeTo(os), a way to access the protected method of a sibling. Use 
  1108. when implementing multi value extended attributes, to save the value of one of 
  1109. the attributes contained. 
  1110.  
  1111. write will normally not find or report errors, but it depends on the actual 
  1112. extended attribute class if errors can occur, and how they are reported. 
  1113.  
  1114.  
  1115. ΓòÉΓòÉΓòÉ <hidden> EA::EA ΓòÉΓòÉΓòÉ
  1116.  
  1117.  
  1118. protected: 
  1119.  EA(EA::Identifier anId); 
  1120.  EA(const EA&); 
  1121.  
  1122. You would normally not call any of these constructors since TEA<T, 
  1123. EA::Identifier> does it for you. Would you, however, the identifier to pass is 
  1124. that used to identify the extended attribute (the EA::Identifier part of TEA.) 
  1125.  
  1126. Errors. 
  1127.  
  1128.       - 
  1129.  
  1130.  
  1131. ΓòÉΓòÉΓòÉ <hidden> EA::operator= ΓòÉΓòÉΓòÉ
  1132.  
  1133.  
  1134. protected: 
  1135.  const EA& operator=(const EA&); 
  1136.  
  1137. You would normally never call the assignment operator of EA, since TEA<T, 
  1138. EA::Identifier> does it for you. 
  1139.  
  1140. Errors. 
  1141.  
  1142.       - 
  1143.  
  1144.  
  1145. ΓòÉΓòÉΓòÉ <hidden> EA::readFrom ΓòÉΓòÉΓòÉ
  1146.  
  1147.  
  1148. protected: 
  1149.  virtual istrstream& readFrom(istrstream&) = 0; 
  1150.  
  1151. Must be overridden by all concrete extended attribute classes to read the 
  1152. content of the attribute. Upon entry, the get pointer of the stream is 
  1153. positioned so that the first byte read, will be the byte immediately following 
  1154. the type identifier. This position is not necessarily the first position in the 
  1155. stream. 
  1156.  
  1157. readFrom will normally not find or report errors, but it depends on the actual 
  1158. extended attribute class if errors can occur, and how they are reported. 
  1159. Objects of collection extended attribute classes, like MTSequenceEA and 
  1160. TSequenceEA<T> might well find and report errors. 
  1161.  
  1162.  
  1163. ΓòÉΓòÉΓòÉ <hidden> EA::writeTo ΓòÉΓòÉΓòÉ
  1164.  
  1165.  
  1166. protected: 
  1167.  virtual ostrstream& writeTo(ostrstream&) = 0; 
  1168.  
  1169. Must be overridden by all concrete extended attribute classes to write the 
  1170. content of the attribute. Upon entry the type identifier is already written. 
  1171. The first byte to write to the stream is the first byte after the identifier of 
  1172. the type for the extended attribute. 
  1173.  
  1174. writeTo will normally not find or report errors, but it depends on the actual 
  1175. extended attribute class if errors can occur, and how they are reported. 
  1176.  
  1177.  
  1178. ΓòÉΓòÉΓòÉ <hidden> StringEA::StringEA ΓòÉΓòÉΓòÉ
  1179.  
  1180.  
  1181. In addition to all the constructors valid for IString, StringEA supports: 
  1182.  
  1183. public: 
  1184.  StringEA(const StringEA& s) 
  1185.  
  1186. Initialise the StringEA object to an exact copy of s. 
  1187.  
  1188. public: 
  1189.  StringEA(const IString& filename, 
  1190.       const IString& eaname) 
  1191.  StringEA(fstreambase& file, 
  1192.       const IString& eaname) 
  1193.  
  1194. Constructs a string extended attribute, and reads its value from the extended 
  1195. attribute pointed to bu filename and eaname. 
  1196.  
  1197. Possible errors are: 
  1198.  
  1199.  Error                    Action 
  1200.  
  1201.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1202.                           error code returned by OS/2. If EA::errorHandler 
  1203.                           returns, an empty StringEA object will be created. 
  1204.  
  1205.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1206.                           If EA::errorHandler returns, an empty StringEA object 
  1207.                           will be created. 
  1208.  
  1209.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1210.                           the type found. If EA::errorHandler returns, an empty 
  1211.                           StringEA object will be created. 
  1212.  
  1213.  For the constructors taking the same arguments as their IString counter parts, 
  1214.  the created object will be initialized with with the flag set to EA::optional. 
  1215.  
  1216.  
  1217. ΓòÉΓòÉΓòÉ <hidden> StringEA::operator= ΓòÉΓòÉΓòÉ
  1218.  
  1219.  
  1220. public: 
  1221.  const StringEA& operator=(const StringEA& s); 
  1222.  
  1223. Make self an exact copy of s and return self reference. 
  1224.  
  1225. public: 
  1226.  const StringEA& operator=(const IString& s); 
  1227.  
  1228. Keep the extended attribute values as is, but assign a new string value to self 
  1229. and return self reference. 
  1230.  
  1231. Possible errors. 
  1232.  
  1233.       - 
  1234.  
  1235.  
  1236. ΓòÉΓòÉΓòÉ <hidden> EA::clone ΓòÉΓòÉΓòÉ
  1237.  
  1238.  
  1239. public: 
  1240.  virtual StringEA* clone(void) const 
  1241.  
  1242. Create an exact copy of self on the heap and return the pointer to it. 
  1243.  
  1244. Possible errors. 
  1245.  
  1246.       - 
  1247.  
  1248.  
  1249. ΓòÉΓòÉΓòÉ <hidden> EA::attributeId ΓòÉΓòÉΓòÉ
  1250.  
  1251.  
  1252. public: 
  1253.  EA::Identifier attributeId(void) 
  1254.  
  1255. Returns StringEA::id. 
  1256.  
  1257. Possible errors are: 
  1258.  
  1259.       - 
  1260.  
  1261.  
  1262. ΓòÉΓòÉΓòÉ <hidden> EA::getFrom ΓòÉΓòÉΓòÉ
  1263.  
  1264.  
  1265. public: 
  1266.  void getFrom(const IString& file, 
  1267.         const IString& name); 
  1268.  
  1269.  void getFrom(fstreambase& file, 
  1270.         const IString& name); 
  1271.  
  1272. Give the string extended attribute object a new value by assigning it the 
  1273. string value read from the named extended attribute. 
  1274.  
  1275. Possible errors are: 
  1276.  
  1277.  Error                    Action 
  1278.  
  1279.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1280.                           error code returned by OS/2. If EA::errorHandler 
  1281.                           returns, the StringEA object will remain unchanged. 
  1282.  
  1283.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1284.                           If EA::errorHandler returns, the StringEA object will 
  1285.                           remain unchanged. 
  1286.  
  1287.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1288.                           the type found. If EA::errorHandler returns, the 
  1289.                           StringEA object will remain unchanged. 
  1290.  
  1291.  
  1292. ΓòÉΓòÉΓòÉ <hidden> EA::storeTo ΓòÉΓòÉΓòÉ
  1293.  
  1294.  
  1295. public: 
  1296.  void storeTo(const IString& file, 
  1297.         const IString& name); 
  1298.  
  1299.  void storeTo(fstreambase& file, 
  1300.         const IString& name); 
  1301.  
  1302. Store the value of the string extended attribute with the name given. 
  1303.  
  1304. Possible errors are: 
  1305.  
  1306.  Error                    Action 
  1307.  
  1308.  EA::WriteError           Call EA::errorHandler with EA::WriteError and the 
  1309.                           error code returned by OS/2. 
  1310.  
  1311.  
  1312. ΓòÉΓòÉΓòÉ <hidden> StringEA::cast ΓòÉΓòÉΓòÉ
  1313.  
  1314.  
  1315. public: 
  1316.  static StringEA* cast(EA*) 
  1317.  static const StringEA* cast(const EA*) 
  1318.  
  1319. Cast pointers of EA to pointers of StringEA. Return the pointer value if, and 
  1320. only if, attributeId() of the object pointed to returns StringEA::id. Return 0 
  1321. otherwise. 
  1322.  
  1323. CAUTION:
  1324. cast is unable to distinguish between StringEA and other implementations of 
  1325. EAT_ASCII, since it compares the attribute id only. 
  1326.  
  1327. Possible errors are: 
  1328.  
  1329.       - 
  1330.  
  1331.  
  1332. ΓòÉΓòÉΓòÉ <hidden> StringEA::allowDynamic ΓòÉΓòÉΓòÉ
  1333.  
  1334.  
  1335. public: 
  1336.  static void allowDynamic(EA::CreatorMap* pCM = 
  1337.               &EA::defaultCreatorMap, 
  1338.               const EA::Creator& = 
  1339.               TEA<StringEA,StringEA::id>::createFrom) 
  1340.  
  1341. Add StringEA to the creator map, making it possible to dynamically create 
  1342. string extended attributes by calling EA::newFrom with that creator map. The 
  1343. StringEA object will be created by a call to the provided creator function. 
  1344.  
  1345. Possible errors. 
  1346.  
  1347.       - 
  1348.  
  1349.  
  1350. ΓòÉΓòÉΓòÉ <hidden> StringEA::disallowDynamic ΓòÉΓòÉΓòÉ
  1351.  
  1352.  
  1353. public: 
  1354.  static void disallowDynamic(EA::CreatorMap* pCM = 
  1355.                &EA::defaultCreatorMap) 
  1356.  
  1357. Remove StringEA from the creator map, making it impossible to dynamically 
  1358. create string extended attributes by calling EA::newFrom with that creator map. 
  1359.  
  1360. Possible errors. 
  1361.  
  1362.       - 
  1363.  
  1364.  
  1365. ΓòÉΓòÉΓòÉ <hidden> StringEA::id ΓòÉΓòÉΓòÉ
  1366.  
  1367.  
  1368. public: 
  1369.  enum { id = EAT_ASCII }; 
  1370.  
  1371. The identifier of string extended attributes. Use (if you can't avoid it,) to 
  1372. compare with attributeId() of objects. It is usually better not to make that 
  1373. comparison, but to use cast instead, and check the return value of the pointer. 
  1374.  
  1375.  
  1376. ΓòÉΓòÉΓòÉ <hidden> StringEA::readFrom ΓòÉΓòÉΓòÉ
  1377.  
  1378.  
  1379. protected: 
  1380.  virtual istrstream& readFrom(istrstream&) 
  1381.  
  1382. Overrides EA::readFrom to read the content of the extended attribute and store 
  1383. its value to the StringEA object itself. 
  1384.  
  1385. Possible errors. 
  1386.  
  1387.       - 
  1388.  
  1389.  
  1390. ΓòÉΓòÉΓòÉ <hidden> StringEA::writeTo ΓòÉΓòÉΓòÉ
  1391.  
  1392.  
  1393. protected: 
  1394.  virtual ostrstream& writeTo(ostrstream&) 
  1395.  
  1396. Overrides EA::writeTo to store the content of the StringEA object. 
  1397.  
  1398. Possible errors. 
  1399.  
  1400.       - 
  1401.  
  1402.  
  1403. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::ErrorFunction ΓòÉΓòÉΓòÉ
  1404.  
  1405.  
  1406. public: 
  1407.  typedef EA* (*ErrorFunction)(EA::Identifier); 
  1408.  
  1409. The type of the error function called by MTSequenceEA when an extended 
  1410. attribute of unknown type is read. 
  1411.  
  1412.  
  1413. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::pCreatorMap ΓòÉΓòÉΓòÉ
  1414.  
  1415.  
  1416. public: 
  1417.  EA::CreatorMap* pCreatorMap; 
  1418.  
  1419. Map used by MTSequenceEA when creating the containing extended attributes. It 
  1420. defaults to &EA::defaultCreatorMap. 
  1421.  
  1422.  
  1423. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::errorFunction ΓòÉΓòÉΓòÉ
  1424.  
  1425.  
  1426. public: 
  1427.  static MTSequenceEA::ErrorFunction errorFunction; 
  1428.  
  1429. Pointer to function, called by MTSequenceEA when reading an extended attribute 
  1430. not found in the creator map. The value returned will be inserted into the 
  1431. sequence. 
  1432.  
  1433. The default function will call EA::errorHandler with TypeMismatchError and the 
  1434. type identifier of the extended attribute read. If EA::errorHandler returns, 
  1435. errorFunction will return 0. 
  1436.  
  1437. To set your own error handler, create a function of type 
  1438. MTSequenceEA::ErrorFunction and set errorFunction to point to it. 
  1439.  
  1440.  
  1441. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::MTSequenceEA ΓòÉΓòÉΓòÉ
  1442.  
  1443.  
  1444. public: 
  1445.  MTSequenceEA(const EA::CreatorMap* = 
  1446.            &EA::defaultCreatorMap); 
  1447.  
  1448. Initialise an empty MTSequenceEA object that creates its contents with the help 
  1449. of the provided creator map. 
  1450.  
  1451. Possible errors. 
  1452.  
  1453.       - 
  1454.  
  1455.  public: 
  1456.   MTSequenceEA(const ISequence<EA*>&, 
  1457.          const EA::CreatorMap* = 
  1458.             &EA::defaultCreatorMap); 
  1459.  
  1460.  Initialise an MTSequenceEA object by copying the contents of the sequence, and 
  1461.  use the creator map provided when reading new values into it. 
  1462.  
  1463.  Possible errors. 
  1464.  
  1465.       - 
  1466.  
  1467.  public: 
  1468.   MTSequenceEA(const IString& filename, 
  1469.          const IString& eaname, 
  1470.          const EA::CreatorMap* = 
  1471.             &EA::defaultCreatorMap); 
  1472.   MTSequenceEA(fstreambase& file, 
  1473.          const IString& eaname, 
  1474.          const EA::CreatorMap* = 
  1475.             &EA::defaultCreatorMap); 
  1476.  
  1477.  Initialise an MTSequenceEA object by reading its contents from the named 
  1478.  extended attribute in the selected file, using the provided creator map when 
  1479.  creating the containing objects. 
  1480.  
  1481.  Possible errors are: 
  1482.  
  1483.  Error                    Action 
  1484.  
  1485.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1486.                           error code returned by OS/2. If EA::errorHandler 
  1487.                           returns, an empty MTSequenceEA object will be 
  1488.                           created. 
  1489.  
  1490.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1491.                           If EA::errorHandler returns, an empty MTSequenceEA 
  1492.                           object will be created. 
  1493.  
  1494.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1495.                           the type found. If EA::errorHandler returns, an empty 
  1496.                           MTSequenceEA object will be created. 
  1497.  
  1498.  If an unknown extended attribute is found when reading the content of the 
  1499.  sequence, MTSequenceEA::errorFunction is called with the type of the unknown 
  1500.  extended attribute. If MTSequenceEA::errorFunction returns, the value returned 
  1501.  is inserted into the sequence. 
  1502.  
  1503.  public: 
  1504.   MTSequenceEA(const MTSequenceEA& mvea); 
  1505.  
  1506.  Initialise an MTSequenceEA object by copying the content of the given sequence 
  1507.  extended attribute. 
  1508.  
  1509.  Possible errors. 
  1510.  
  1511.       - 
  1512.  
  1513.  
  1514. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::getCodePage ΓòÉΓòÉΓòÉ
  1515.  
  1516.  
  1517. public: 
  1518.  unsigned short getCodePage(void) const 
  1519.  
  1520. Return the code page of the MTSequenceEA object. Code page 0 means the default 
  1521. code page of the system. The code page of MTSequenceEA objects defaults to 0. 
  1522.  
  1523. Possible errors. 
  1524.  
  1525.       - 
  1526.  
  1527.  
  1528. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::setCodePage ΓòÉΓòÉΓòÉ
  1529.  
  1530.  
  1531. public: 
  1532.  void setCodePage(unsigned short cp) 
  1533.  
  1534. Set the code page of the MTSequenceEA object. By default, the code page is 0, 
  1535. meaning the default code page of the system. 
  1536.  
  1537. Possible errors. 
  1538.  
  1539.       - 
  1540.  
  1541.  
  1542. ΓòÉΓòÉΓòÉ <hidden> EA::attributeId ΓòÉΓòÉΓòÉ
  1543.  
  1544.  
  1545. public: 
  1546.  EA::Identifier attributeId(void) 
  1547.  
  1548. Returns MTSequenceEA::id. 
  1549.  
  1550. Possible errors are: 
  1551.  
  1552.       - 
  1553.  
  1554.  
  1555. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::getFrom ΓòÉΓòÉΓòÉ
  1556.  
  1557.  
  1558. public: 
  1559.  void getFrom(const IString& file, 
  1560.         const IString& name); 
  1561.  
  1562.  void getFrom(fstreambase& file, 
  1563.         const IString& name); 
  1564.  
  1565. Give the sequence extended attribute object a new value by assigning it the 
  1566. value read from the named extended attribute. Possible errors are: 
  1567.  
  1568.  Error                    Action 
  1569.  
  1570.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1571.                           error code returned by OS/2. If EA::errorHandler 
  1572.                           returns, the MTSequenceEA object will remain 
  1573.                           unchanged. 
  1574.  
  1575.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1576.                           If EA::errorHandler returns, the MTSequenceEA object 
  1577.                           will remain unchanged. 
  1578.  
  1579.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1580.                           the type found. If EA::errorHandler returns, the 
  1581.                           MTSequenceEA object will remain unchanged. 
  1582.  
  1583.  If an unknown extended attribute is found when reading the content of the 
  1584.  sequence, MTSequenceEA::errorFunction is called with the type of the unknown 
  1585.  extended attribute. If MTSequenceEA::errorFunction returns, the value returned 
  1586.  is inserted into the sequence. 
  1587.  
  1588.  
  1589. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::storeTo ΓòÉΓòÉΓòÉ
  1590.  
  1591.  
  1592. public: 
  1593.  void storeTo(const IString& file, 
  1594.         const IString& name); 
  1595.  
  1596.  void storeTo(fstreambase& file, 
  1597.         const IString& name); 
  1598.  
  1599. Store the value of the sequence extended attribute with the name given. 
  1600.  
  1601. Possible errors are: 
  1602.  
  1603.  Error                    Action 
  1604.  
  1605.  EA::WriteError           Call EA::errorHandler with EA::WriteError and the 
  1606.                           error code returned by OS/2. 
  1607.  
  1608.  
  1609. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::cast ΓòÉΓòÉΓòÉ
  1610.  
  1611.  
  1612. public: 
  1613.  static MTSequenceEA* cast(EA*) 
  1614.  static const MTSequenceEA* cast(const EA*) 
  1615.  
  1616. Cast pointers of EA to pointers of MTSequenceEA. Return the pointer value if, 
  1617. and only if, attributeId() of the object pointed to returns MTSequenceEA::id. 
  1618. Return 0 otherwise. 
  1619.  
  1620. CAUTION:
  1621. cast is unable to distinguish between MTSequenceEA and other implementations of 
  1622. EAT_MVMT, since it compares the attribute id only. 
  1623.  
  1624. Possible errors are: 
  1625.  
  1626.       - 
  1627.  
  1628.  
  1629. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::allowDynamic ΓòÉΓòÉΓòÉ
  1630.  
  1631.  
  1632. public: 
  1633.  static void allowDynamic(EA::CreatorMap* pCM 
  1634.               = &EA::defaultCreatorMap, 
  1635.               const EA::Creator& creator = 
  1636.               TEA<MTSequenceEA::MTSequenceEA::id>::createFrom) 
  1637.  
  1638. Add MTSequenceEA to the creator map, making it possible to dynamically create 
  1639. string extended attributes by calling EA::newFrom with that creator map. The 
  1640. MTSequenceEA object will be created with the provided creator function. 
  1641.  
  1642. Possible errors are: 
  1643.  
  1644.       - 
  1645.  
  1646.  
  1647. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::disallowDynamic ΓòÉΓòÉΓòÉ
  1648.  
  1649.  
  1650. public: 
  1651.  static void disallowDynamic(EA::CreatorMap* pCM 
  1652.                = &EA::defaultCreatorMap) 
  1653.  
  1654. Remove MTSequenceEA from the creator map, making it impossible to dynamically 
  1655. create string extended attributes by calling EA::newFrom with that creator map. 
  1656.  
  1657. Possible errors are: 
  1658.  
  1659.       - 
  1660.  
  1661.  
  1662. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::id ΓòÉΓòÉΓòÉ
  1663.  
  1664.  
  1665. public: 
  1666.  enum { id = EAT_MVMT }; 
  1667.  
  1668. The identifier of multi value sequence extended attributes. Use (if you can't 
  1669. avoid it,) to compare with attributeId() of objects. It is usually better not 
  1670. to make that comparison, but to use cast instead, and check the return value of 
  1671. the pointer. 
  1672.  
  1673.  
  1674. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::readFrom ΓòÉΓòÉΓòÉ
  1675.  
  1676.  
  1677. protected: 
  1678.  virtual istrstream& readFrom(istrstream&) 
  1679.  
  1680. Overrides EA::readFrom to read the content of the extended attribute and store 
  1681. its value to the MTSequenceEA object itself. 
  1682.  
  1683. Possible errors are: 
  1684.  
  1685.  Error                         Action 
  1686.  
  1687.  Unknown type read.            Calls MTSequenceEA::errorFunction with the type 
  1688.                                of the unknown extended attribute. If 
  1689.                                MTSequenceEA::errorFunction returns, the value 
  1690.                                returned is inserted into the sequence. 
  1691.  
  1692.  
  1693. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::writeTo ΓòÉΓòÉΓòÉ
  1694.  
  1695.  
  1696. protected: 
  1697.  virtual ostrstream& writeTo(ostrstream&) 
  1698.  
  1699. Overrides EA::writeTo to store the content of the MTSequenceEA object. 
  1700.  
  1701. Possible errors are: 
  1702.  
  1703.       - 
  1704.  
  1705.  
  1706. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::~MTSequenceEA ΓòÉΓòÉΓòÉ
  1707.  
  1708.  
  1709. public: 
  1710.  virtual ~MTSequenceEA(void) 
  1711.  
  1712. Destroys the MTSequenceEA object and deallocates all of its contents. 
  1713.  
  1714. Note:  All EA objects pointed to by the MTSequenceEA object by the time of 
  1715.        destruction will be deallocated by a call to operator delete. If any of 
  1716.        the pointers is not to an object allocated on heap, a run time error is 
  1717.        most likely to occur. The reason for this behaviour is to avoid memory 
  1718.        leaks if an MTSequenceEA object is read when one is not expected. 
  1719.  
  1720.  Possible errors are: 
  1721.  
  1722.       - 
  1723.  
  1724.  
  1725. ΓòÉΓòÉΓòÉ <hidden> MTSequenceEA::operator= ΓòÉΓòÉΓòÉ
  1726.  
  1727.  
  1728. In order to make a copy assignment operation work without causing memory leaks, 
  1729. both versions of operator= empties the contents, thus freeing all the pointers 
  1730. in the collection, before the copy. 
  1731.  
  1732. Note:  Since operator delete will be executed on all pointers, any pointer 
  1733.        referring to an element not allocated on heap is likely to cause a run 
  1734.        time error. 
  1735.  
  1736.  public: 
  1737.   const MTSequenceEA& operator=(const MTSequenceEA& mvea); 
  1738.  
  1739.  Make self an exact copy of mvea. The contents of mvea will be cloned to avoid 
  1740.  getting several pointers to the same elements, and potential dangling pointers 
  1741.  at a later time. 
  1742.  
  1743.  Possible errors are: 
  1744.  
  1745.       - 
  1746.  
  1747.  public: 
  1748.   const MTSequenceEA& operator=(const ISequence<EA*>& isea); 
  1749.  
  1750.  Keep the state of self, except for the content of the collection, which is 
  1751.  made an exact copy of isea. The contents of isea will be cloned to avoid 
  1752.  getting several pointers to the same elements, and potential dangling pointers 
  1753.  at a later time. 
  1754.  
  1755.  Possible errors are: 
  1756.  
  1757.       - 
  1758.  
  1759.  
  1760. ΓòÉΓòÉΓòÉ <hidden> EA::clone ΓòÉΓòÉΓòÉ
  1761.  
  1762.  
  1763. public: 
  1764.  virtual MTSequenceEA* clone(void) const; 
  1765.  
  1766. Create an exact deep copy of self on the heap and return the pointer to it. 
  1767. Used by the copy constructors and assignment operators of extended attribute 
  1768. collections such as MTSequenceEA and TSequenceEA<T>. 
  1769.  
  1770. clone itself does not find or report any errors, but since it does a deep copy 
  1771. of the collection, some of its containing objects might. If and how this is 
  1772. done depends on the type of the containig objects. 
  1773.  
  1774.  
  1775. ΓòÉΓòÉΓòÉ <hidden> EA::setCreatorMap ΓòÉΓòÉΓòÉ
  1776.  
  1777.  
  1778. public: 
  1779.  virtual void setCreatorMap(const EA::CreatorMap*) 
  1780.  
  1781. Override of the empty default function in EA. It sets the 
  1782. MTSequenceEA::pCreatorMap to the map passed, to make sure children are created 
  1783. from the correct creator map. 
  1784.  
  1785. Possible errors are: 
  1786.  
  1787.       - 
  1788.  
  1789.  
  1790. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::TSequenceEA ΓòÉΓòÉΓòÉ
  1791.  
  1792.  
  1793. public: 
  1794.  TSequenceEA(EA::CreatorMap* = &EA::defaultCreatorMap) 
  1795.  
  1796. Initialise a an empty TSequenceEA<T> object. 
  1797.  
  1798. public: 
  1799.  TSequenceEA(const TSequenceEA<T>& t) 
  1800.  
  1801. Copy constructor. Initialise a TSequenceEA<T> object by copying the contents 
  1802. and status of t. 
  1803.  
  1804. public: 
  1805.  TSequenceEA(const ISequence<T*>& t, 
  1806.        EA::CreatorMap* = &EA::defaultCreatorMap) 
  1807.  
  1808. Initialise a TSequenceEA<T> object, by copying the contents of the provided 
  1809. ISequence<T*> object. 
  1810.  
  1811. public: 
  1812.  TSequenceEA(const IString& filename, 
  1813.        const IString& eaname, 
  1814.        EA::CreatorMap* = &EA::defaultCreatorMap) 
  1815.  TSequenceEA(fstreambase& file, 
  1816.        const IString& eaname, 
  1817.        EA::CreatorMap* = &EA::defaultCreatorMap) 
  1818.  
  1819. Initialise a TSequenceEA<T> object by reading its contents from the named 
  1820. extended attribute of the file. 
  1821.  
  1822. Possible errors are: 
  1823.  
  1824.  Error                    Action 
  1825.  
  1826.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  1827.                           error code returned by OS/2. If EA::errorHandler 
  1828.                           returns, an empty TSequenceEA<T> object will be 
  1829.                           created. 
  1830.  
  1831.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  1832.                           If EA::errorHandler returns, an empty TSequenceEA<T> 
  1833.                           object will be created. 
  1834.  
  1835.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  1836.                           the type found. If EA::errorHandler returns, an empty 
  1837.                           TSequenceEA<T> object will be created. 
  1838.  
  1839.  Note:  In addition to the above error situations, it is possible that any of 
  1840.         the containing objects read into the sequence will find and report 
  1841.         errors. If that is done, and how, depends on the type of object read. 
  1842.  
  1843.  
  1844. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::operator= ΓòÉΓòÉΓòÉ
  1845.  
  1846.  
  1847. To avoid memory leaks, both versions of operator= empty the content of self, 
  1848. and deallocates all pointers, before deep copying the content of the source. 
  1849.  
  1850. Note:  Since operator delete will be executed on all pointers, any pointer 
  1851.        referring to an element not allocated on heap is likely to cause a run 
  1852.        time error. 
  1853.  
  1854.  public: 
  1855.   const TSequenceEA<T>& operator=(const TSequenceEA<T>& t) 
  1856.  
  1857.  Copy the content and status of t to self and return self reference. 
  1858.  
  1859.  Possible errors are: 
  1860.  
  1861.       - 
  1862.  
  1863.    const TSequenceEA<T>& operator=(const ISequence<T*>& t) 
  1864.  
  1865.  Keep the state of the extended attribute object as is, but assign it new 
  1866.  values from the ISequence passed. 
  1867.  
  1868.  Possible errors are: 
  1869.  
  1870.       - 
  1871.  
  1872.  Note:  It is possible that some of the contained objects will find and report 
  1873.         errors. If that happens, and how, depends on the type of the contained 
  1874.         objects. 
  1875.  
  1876.  
  1877. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::~TSequenceEA ΓòÉΓòÉΓòÉ
  1878.  
  1879.  
  1880. public: 
  1881.  virtual ~TSequenceEA(void) 
  1882.  
  1883. Destructor. 
  1884.  
  1885. Note:  Unlike the destructor for ISequence, the destructor for TSequenceEA<T> 
  1886. deallocates all pointers to its contents. This is to avoid memory leaks in 
  1887. situations where a TSequenceEA<T> is read when you do not expect one. 
  1888.  
  1889. Warning: If there are extended attribute objects in the sequence that are not 
  1890. allocated on heap, when the destructor is called, a run-time error is very 
  1891. likely to occur since operator delete is called on every pointer in the 
  1892. sequence. 
  1893.  
  1894. Possible errors are: 
  1895.  
  1896.       - 
  1897.  
  1898.  Note:  It is possible that some of the contained objects will find and report 
  1899.         errors. If that happens, and how, depends on the type of the contained 
  1900.         objects. 
  1901.  
  1902.  
  1903. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::allowDynamic ΓòÉΓòÉΓòÉ
  1904.  
  1905.  
  1906. public: 
  1907.  static void allowDynamic(EA::CreatorMap* pCM = 
  1908.               &EA::defaultCreatorMap, 
  1909.               const EA::Creator& creator = 
  1910.               TSequenceEA<T>::createFrom) 
  1911.  
  1912. Add TSequenceEA<T> to the creator map, making it possible to dynamically create 
  1913. typed sequence extended attributes by calling EA::newFrom with that creator 
  1914. map. The TSequenceEA<T> object will be created by a call to the provided 
  1915. creator function. 
  1916.  
  1917. Possible errors. 
  1918.  
  1919.       - 
  1920.  
  1921.  
  1922. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::disallowDynamic ΓòÉΓòÉΓòÉ
  1923.  
  1924.  
  1925. public: 
  1926.  static void disallowDynamic(EA::CreatorMap* pCM = 
  1927.                &EA::defaultCreatorMap) 
  1928.  
  1929. Remove the creator of TSequenceEA<T> from the provided creator map, making it 
  1930. impossible to dynamically create TSequenceEA<T> objects from it. 
  1931.  
  1932. Possible errors are: 
  1933.  
  1934.       - 
  1935.  
  1936.  
  1937. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::cast ΓòÉΓòÉΓòÉ
  1938.  
  1939.  
  1940. public: 
  1941.  static TSequenceEA<T>* cast(EA*) 
  1942.  static const TSequenceEA<T>* cast(const EA*) 
  1943.  
  1944. Cast pointers of EA to pointers of TSequenceEA<T>. Return the pointer value if, 
  1945. and only if, attributeId() of the object equals SequenceEA::id and its 
  1946. contentId() returns T::elementId. Otherwise the value returned will be 0. 
  1947.  
  1948. CAUTION:
  1949. cast is unable to distinguish between TSequenceEA<T> and other implementations 
  1950. of EAT_MVST, or TSequenceEA<T2> where T::id == T2::id for that matter, since 
  1951. only the type identifiers are compared. 
  1952.  
  1953.  
  1954. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::elementId ΓòÉΓòÉΓòÉ
  1955.  
  1956.  
  1957. template <class T> 
  1958. class TSequenceEA ┬╖┬╖┬╖ 
  1959. { 
  1960.  enum { elementId = T::id } 
  1961.  
  1962. Constant for accessing the type identifier of the class that TSequenceEA<T> is 
  1963. parametrised with. For example, TSequenceEA<StringEA>::elementId == 
  1964. StringEA::id. 
  1965.  
  1966. There is little reason to use this constant. It is used internally by 
  1967. TSequenceEA<T>::cast. 
  1968.  
  1969.  
  1970. ΓòÉΓòÉΓòÉ <hidden> EA::clone ΓòÉΓòÉΓòÉ
  1971.  
  1972.  
  1973. public: 
  1974.  virtual TSequenceEA<T>* clone(void) const 
  1975.  
  1976. Create an exact deep copy of self on the heap and return the pointer to it. 
  1977. Used by the copy constructors and assignment operators of extended attribute 
  1978. collections such as MTSequenceEA and TSequenceEA<T>. 
  1979.  
  1980. clone itself does not find or report any errors, but since it does a deep copy 
  1981. of the collection, some of the containing objects might. If and how this is 
  1982. done depends on the type of the containig objects. 
  1983.  
  1984.  
  1985. ΓòÉΓòÉΓòÉ <hidden> EA::attributeId ΓòÉΓòÉΓòÉ
  1986.  
  1987.  
  1988. public: 
  1989.  EA::Identifier attributeId(void) const 
  1990.  
  1991. Returns SequenceEA::id 
  1992.  
  1993. Possible errors. 
  1994.  
  1995.       - 
  1996.  
  1997.  
  1998. ΓòÉΓòÉΓòÉ <hidden> EA::getFrom ΓòÉΓòÉΓòÉ
  1999.  
  2000.  
  2001. public: 
  2002.  void getFrom(const IString& file, 
  2003.         const IString& name); 
  2004.  void getFrom(fstreambase& file, 
  2005.         const IString& name); 
  2006.  
  2007. Read the value of the named extended attribute for the file into the 
  2008. TSequenceEA<T> object. 
  2009.  
  2010. Possible errors are: 
  2011.  
  2012.  Error                    Action 
  2013.  
  2014.  EA::ReadError            Call EA::errorHandler with EA::ReadError and the 
  2015.                           error code returned by OS/2. If EA::errorHandler 
  2016.                           returns, the TSequenceEA<T> object will remains 
  2017.                           unchanged. 
  2018.  
  2019.  EA::NoSuchEAError        Call EA::errorHandler with EA::NoSuchEAError and 0. 
  2020.                           If EA::errorHandler returns, the TSequenceEA<T> 
  2021.                           object will remain unchanged. 
  2022.  
  2023.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  2024.                           the type found. If EA::errorHandler returns, the 
  2025.                           TSequenceEA<T> object will remain unchanged. 
  2026.  
  2027.  TypeMismatchError is called both if the named attribute is not a typed 
  2028.  sequence extended attribute, and if the type of the content read is not that 
  2029.  of T. 
  2030.  
  2031.  Note:  In addition to the above, it is possible that some of the contained 
  2032.         objects will find and report errors. If and how that is done depends on 
  2033.         the type of the objects. 
  2034.  
  2035.  
  2036. ΓòÉΓòÉΓòÉ <hidden> EA::storeTo ΓòÉΓòÉΓòÉ
  2037.  
  2038.  
  2039. public: 
  2040.  void storeTo(const IString& file, 
  2041.         const IString& name); 
  2042.  void storeTo(fstreambase& file, 
  2043.         const IString& name); 
  2044.  
  2045. Write the value of the typed extended attribute sequence to the file using the 
  2046. name given. 
  2047.  
  2048. Possible errors are: 
  2049.  
  2050.  Error                    Action 
  2051.  
  2052.  EA::WriteError           Call EA::errorHandler with EA::WriteError and the 
  2053.                           error code returned by OS/2. 
  2054.  
  2055.  
  2056. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::readFrom ΓòÉΓòÉΓòÉ
  2057.  
  2058.  
  2059. protected: 
  2060.  virtual istrstream& readFrom(istrstream& is) 
  2061.  
  2062. Overrides EA::readFrom to read the content of the typed sequence extended 
  2063. attribute and store its value in the TSequenceEA<T> 
  2064.  
  2065. Possible errors are: 
  2066.  
  2067.  Error                    Action 
  2068.  
  2069.  EA::TypeMismatchError    Call EA::errorHandler with EA::TypeMismatchError and 
  2070.                           the type found. This means that the content type of 
  2071.                           the sequence (i.e. T::id) was not the content type 
  2072.                           read from the stream. 
  2073.  
  2074.  Note:  In addition to the above, it is possible that some of the contained 
  2075.         objects will find and report errors. If and how that is done depends on 
  2076.         the type of the objects. 
  2077.  
  2078.  
  2079. ΓòÉΓòÉΓòÉ <hidden> TSequenceEA<T>::writeTo ΓòÉΓòÉΓòÉ
  2080.  
  2081.  
  2082. protected: 
  2083.  virtual ostrstream& writeTo(ostrstream& os) 
  2084.  
  2085. Overrides EA::writeTo to write the content of the typed sequence extended 
  2086. attribute. 
  2087.  
  2088. Possible errors are: 
  2089.  
  2090.       - 
  2091.  
  2092.  Note:  It is possible that some of the contained objects will find and report 
  2093.         errors. If and how that is done depends on the type of the objects. 
  2094.  
  2095.  
  2096. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::id ΓòÉΓòÉΓòÉ
  2097.  
  2098.  
  2099. template <class T, EA::Identifier eaid> 
  2100. class TEA 
  2101. { 
  2102. public: 
  2103.  struct { id = eaid; }; 
  2104. ┬╖┬╖┬╖ 
  2105. A named class constant with the value passed when instantiating TEA. 
  2106. Representing the type for the concrete extended attribute object inheriting 
  2107. from TEA. 
  2108.  
  2109.  
  2110. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::cast ΓòÉΓòÉΓòÉ
  2111.  
  2112.  
  2113. template <class T,EA::Identifier eaid> 
  2114. class TEA<T,eaid> 
  2115. { 
  2116. public: 
  2117.  static T* cast(EA*); 
  2118.  static const T* cast(const EA*); 
  2119.  ┬╖┬╖┬╖ 
  2120.  
  2121. Cast pointers to EA to pointers of class T if, and only if, the type identifier 
  2122. of the EA object is identical to the typeid TEA is instantiated with (i.e. 
  2123. T::id.) Return 0 otherwise. 
  2124.  
  2125. CAUTION:
  2126. cast is unable to differ between objects of class T and other implementation of 
  2127. T::id, since only the attribute id is compared. 
  2128.  
  2129. Possible errors are: 
  2130.  
  2131.       - 
  2132.  
  2133.  
  2134. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::allowDynamic ΓòÉΓòÉΓòÉ
  2135.  
  2136.  
  2137. public: 
  2138. static void allowDynamic(EA::CreatorMap* pCM = 
  2139.              &EA::defaultCreatorMap, 
  2140.              const EA::Creator& = TEA<T,EA::Identifier>::createFrom); 
  2141.  
  2142. Add the creator of the descendant of TEA to the provided creator map. 
  2143.  
  2144. Note for designers of new classes  A default creator is provided by TEA. If you 
  2145. need a different one, you must write an allowDynamic function for your own 
  2146. class, and a special creator function for it. If you have only a specific 
  2147. creator function, override allowDynamic to take the creator function as its 
  2148. default argument, and call TEA::allowDynamic from your own override. 
  2149.  
  2150. Possible errors are: 
  2151.  
  2152.       - 
  2153.  
  2154.  
  2155. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::disallowDynamic ΓòÉΓòÉΓòÉ
  2156.  
  2157.  
  2158. public: 
  2159.  static void 
  2160.   disallowDynamic(EA::CreatorMap* pCM = 
  2161.           &EA::defaultCreatorMap); 
  2162.  
  2163. Remove the creator of the descendant of TEA from the provided creator map. 
  2164.  
  2165. Possible errors are: 
  2166.  
  2167.       - 
  2168.  
  2169.  
  2170. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::TEA ΓòÉΓòÉΓòÉ
  2171.  
  2172.  
  2173. protected: 
  2174.  TEA(void); 
  2175.  TEA(const TEA<T, EA::Identifier>&t); 
  2176.  
  2177. Initialise the extended attribute base object. Use when implementing descendant 
  2178. extended attribute classes. 
  2179.  
  2180. Possible errors are: 
  2181.  
  2182.       - 
  2183.  
  2184.  
  2185. ΓòÉΓòÉΓòÉ <hidden> TEA<T,EA::Identifier>::operator= ΓòÉΓòÉΓòÉ
  2186.  
  2187.  
  2188. protected: 
  2189.  const TEA<T, EA::Identifier>& operator=(const TEA<T, EA::Identifier>& t) 
  2190.  
  2191. Copy the content and status of t to self and return self reference. Use in the 
  2192. implementation of descendants from TEA<T, EA::Identifier>. 
  2193.  
  2194. Possible errors are: 
  2195.  
  2196.       - 
  2197.  
  2198.  
  2199. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::errorFunction ΓòÉΓòÉΓòÉ
  2200.  
  2201.  
  2202. public: 
  2203.  static EA* (*errorFunction)(EA::Identifier); 
  2204.  
  2205. The error function called if a TSequenceEA<T>, for which allowDynamic has not 
  2206. been called (but another TSequenceEA<T> has been allowed,) is attempted to be 
  2207. read anonymously (by EA::newFrom or as an element in MTSequenceEA) The default 
  2208. function throws an EATSequenceEAInstError exception, with the identifier of the 
  2209. content type as the error code. To override this function, simply assign it 
  2210. your own. The value returned from the function (if it returns) is what 
  2211. EA::newFrom or MTSequenceEA gets. 
  2212.  
  2213.  
  2214. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::~SequenceEA ΓòÉΓòÉΓòÉ
  2215.  
  2216.  
  2217. public: 
  2218.  virtual ~SequenceEA(void) 
  2219.  
  2220. Destroy the SequenceEA object. 
  2221.  
  2222. Possible errors are: 
  2223.  
  2224.       - 
  2225.  
  2226.  
  2227. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::getCodePage ΓòÉΓòÉΓòÉ
  2228.  
  2229.  
  2230. public: 
  2231.  unsigned short getCodePage(void) const; 
  2232.  
  2233. Return the code page used by the TSequenceEA<T> object. Code page 0 means the 
  2234. same code page as used by the application. 
  2235.  
  2236. Possible errors are: 
  2237.  
  2238.       - 
  2239.  
  2240.  
  2241. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::setCodePage ΓòÉΓòÉΓòÉ
  2242.  
  2243.  
  2244. public: 
  2245.  void setCodePage(unsigned short p) 
  2246.  
  2247. Set the code page for the instance of TSequenceEA<T>. Code page 0 means to use 
  2248. the same code page as the application. 
  2249.  
  2250. Possible errors are: 
  2251.  
  2252.       - 
  2253.  
  2254.  
  2255. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::contentId ΓòÉΓòÉΓòÉ
  2256.  
  2257.  
  2258. public: 
  2259.  EA::Identifier contentId(void) const 
  2260.  
  2261. Returns the identifier of the content type, i.e. TSequenceEA<T>::contentId() 
  2262. returns T::id. Since you will normally not work with SequenceEA directly, but 
  2263. rather instances of TSequenceEA<T>, there will be little need for this 
  2264. function. It is used internally by the TSequenceEA<T> override of 
  2265. TEA<T,EA::Identifier>::cast functions. 
  2266.  
  2267. Possible errors are: 
  2268.  
  2269.       - 
  2270.  
  2271.  
  2272. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::clone ΓòÉΓòÉΓòÉ
  2273.  
  2274.  
  2275. public: 
  2276.  virtual SequenceEA* clone(void) const 
  2277.  
  2278. Returns 0. This version of clone should never be called, since TSequenceEA<T> 
  2279. overrides it. 
  2280.  
  2281. Possible errors are: 
  2282.  
  2283.       - 
  2284.  
  2285.  
  2286. ΓòÉΓòÉΓòÉ <hidden> EA::setCreatorMap ΓòÉΓòÉΓòÉ
  2287.  
  2288.  
  2289. public: 
  2290.  virtual void setCreatorMap(const EA::CreatorMap*) 
  2291.  
  2292. Override of the empty default function in EA. It sets the 
  2293. SequenceEA::pCreatorMap to the map passed, to make sure children of the 
  2294. TSequenceEA<T> object are created from the correct creator map. 
  2295.  
  2296. Possible errors are: 
  2297.  
  2298.       - 
  2299.  
  2300.  
  2301. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::pCreatorMap ΓòÉΓòÉΓòÉ
  2302.  
  2303.  
  2304. protected: 
  2305.  const EA::CreatorMap* pCreatorMap 
  2306.  
  2307. Creator map passed to the containing objects of the TSequenceEA<T> inheriting 
  2308. SequenceEA, as they are created, to make sure they are read from the creator 
  2309. map specified. This is only needed if the type of T is a collection class. 
  2310.  
  2311.  
  2312. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::allowDynamic ΓòÉΓòÉΓòÉ
  2313.  
  2314.  
  2315. protected: 
  2316.  static void allowDynamic(EA::CreatorMap* pCM, 
  2317.               const EA::Creator& creator = SequenceEA::createFrom) 
  2318.  
  2319. Override of the default from TEA, to allow descendants of SequenceEA to allow 
  2320. creation of SequenceEA objects through the private creator function 
  2321. SequenceEA::createFrom. 
  2322.  
  2323.  
  2324. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::SequenceEA ΓòÉΓòÉΓòÉ
  2325.  
  2326.  
  2327. protected: 
  2328.  SequenceEA(EA::Identifier id, 
  2329.        EA::CreatorMap* pCM = &EA::defaultCreatorMap); 
  2330.  SequenceEA(const SequenceEA& mvea); 
  2331.  
  2332. Initialise instance of SequenceEA. Used by the constructors for TSequenceEA<T>. 
  2333.  
  2334. Possible errors are: 
  2335.  
  2336.       - 
  2337.  
  2338.  
  2339. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::operator= ΓòÉΓòÉΓòÉ
  2340.  
  2341.  
  2342. protected: 
  2343.  const SequenceEA& operator=(const SequenceEA& mvea); 
  2344.  
  2345. Copy content and status of mvea to self and return self reference. Used by the 
  2346. assignment operator in TSequenceEA<T> 
  2347.  
  2348. Possible errors are: 
  2349.  
  2350.       - 
  2351.  
  2352.  
  2353. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::writeTo ΓòÉΓòÉΓòÉ
  2354.  
  2355.  
  2356. protected: 
  2357.  virtual ostrstream& writeTo(ostrstream& os) 
  2358.  
  2359. Override of EA::writeTo that does nothing. Should never be called since 
  2360. TSequenceEA<T> overrides it. 
  2361.  
  2362. Possible errors are: 
  2363.  
  2364.       - 
  2365.  
  2366.  
  2367. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::readFrom ΓòÉΓòÉΓòÉ
  2368.  
  2369.  
  2370. protected: 
  2371.  virtual istrstream& readFrom(istrstream& is) 
  2372.  
  2373. Override of EA::readFrom that does nothing. Should never be called since 
  2374. TSequenceEA<T> overrides it. 
  2375.  
  2376. Possible errors are: 
  2377.  
  2378.       - 
  2379.  
  2380.  
  2381. ΓòÉΓòÉΓòÉ <hidden> SequenceEA::id ΓòÉΓòÉΓòÉ
  2382.  
  2383.  
  2384. public: 
  2385.  enum { id = EAT_MVST }; 
  2386.  
  2387.  
  2388. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  2389.  
  2390. Destructor for TEA. Does nothing explicit, since TEA does not have any data of 
  2391. its own.