home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / VALUERTN.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  9KB  |  201 lines
  1. /* @(#)Z 1.4 com/src/cm/ValueRtn.h, odstorage, od96os2, odos29646d 96/11/15 15:27:43 (96/10/29 09:20:25) */
  2. /*====START_GENERATED_PROLOG======================================
  3.  */
  4. /*
  5.  *   COMPONENT_NAME: odstorage
  6.  *
  7.  *   CLASSES: none
  8.  *
  9.  *   ORIGINS: 82,27
  10.  *
  11.  *
  12.  *   (C) COPYRIGHT International Business Machines Corp. 1995,1996
  13.  *   All Rights Reserved
  14.  *   Licensed Materials - Property of IBM
  15.  *   US Government Users Restricted Rights - Use, duplication or
  16.  *   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  17.  *       
  18.  *   IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  19.  *   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20.  *   PURPOSE. IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  21.  *   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  22.  *   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  23.  *   OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
  24.  *   OR PERFORMANCE OF THIS SOFTWARE.
  25.  */
  26. /*====END_GENERATED_PROLOG========================================
  27.  */
  28.  
  29. /*
  30.     File:        ValueRtn.h
  31.  
  32.     Contains:    Container Manager Common Value Routines Interfaces
  33.  
  34.     Written by:    Ira L. Ruben
  35.  
  36.     Owned by:    Ed Lai
  37.  
  38.     Copyright:    ⌐ 1992-1994 by Apple Computer, Inc., all rights reserved.
  39.  
  40.     Change History (most recent first):
  41.  
  42.          <2>     8/26/94    EL        #1182275 Container merging.
  43.          <2>      6/3/94    EL        Rename Values.h/c to ValueRtn.h/c.
  44.          <1>      2/3/94    EL        first checked in
  45.  
  46.     To Do:
  47. */
  48.  
  49. /*---------------------------------------------------------------------------*
  50.  |                                                                           |
  51.  |                          <<<   ValueRtn.h    >>>                          |
  52.  |                                                                           |
  53.  |             Container Manager Common Value Routines Interfaces            |
  54.  |                                                                           |
  55.  |                               Ira L. Ruben                                |
  56.  |                                  7/22/92                                  |
  57.  |                                                                           |
  58.  |                     Copyright Apple Computer, Inc. 1992-1994              |
  59.  |                           All rights reserved.                            |
  60.  |                                                                           |
  61.  *---------------------------------------------------------------------------*
  62.  
  63.  This file contains the interfaces to the various routines needed for value operations,
  64.  e.g., CMWriteValueData() CMDeleteValueData(), etc.  Some of these routines are used when
  65.  applying updates at open time (insert and delete data, move a value header).
  66. */
  67.  
  68. #ifndef __VALUEROUTINES__
  69. #define __VALUEROUTINES__
  70.  
  71.  
  72. #ifndef __CMTYPES__
  73. #include "CMTypes.h"
  74. #endif
  75. #ifndef __CM_API_TYPES__
  76. #include "CMAPITyp.h"
  77. #endif
  78.  
  79. struct TOCValueHdr;
  80. struct TOCValue;
  81. struct TOCObject;
  82.  
  83.  
  84.                                                                     CM_CFUNCTIONS
  85.  
  86.  
  87. struct TOCValue *cmGetStartingValue(struct TOCValueHdr *theValueHdr,
  88.                                                                       CM_ULONG startingOffset, 
  89.                                                                         CM_ULONG *valueOffset);
  90.     /*
  91.     This returns the TOCValuePtr to the value entry which contains the stream starting 
  92.     offset, startingOffset.  Also returned in valueOffset is the offset within the returned
  93.     value entry which is the startingOffset'th byte.
  94.     
  95.     Note, NULL is returned for the value pointer if we cannot find the offset. This could 
  96.     happen when the startingOffset is beyond the end of the value.
  97.     
  98.     This routine is necessary because of continued values which are represented by a list of
  99.     TOCValue entries off of a TOCValueHdr.  Each entry represents a discontinous segment of
  100.     the value data which is always viewed as a stream of contiguous bytes even though they 
  101.     are not.  This routine is one of those that allows its caller to view the stream as
  102.     contiguous.
  103.     */
  104.     
  105.  
  106. CM_ULONG cmRead1ValueData(struct TOCValue *theValue, CM_UCHAR *buffer,
  107.                                                     CM_ULONG offset,CM_ULONG maxSize);
  108.     /*
  109.     This routine copies the data for the specified value (NOT a value header -- continued
  110.     values are not worried about here), starting at the specified offset, TO the caller's
  111.     buffer.  A maximum of maxSize characters or the size of the data, which ever is smaller,
  112.     is copied.  The function returns the amount of data copied to the buffer.
  113.     
  114.     Note, this routine handles the special cases for immediate data.
  115.     */
  116.  
  117.  
  118. CM_ULONG cmOverwrite1ValueData(struct TOCValue *theValue, CM_UCHAR *buffer,
  119.                                                              CM_ULONG offset, CM_ULONG size);
  120.     /*
  121.     This routine copies the data for the specified value (NOT a value header -- continued
  122.     values are not worried about here), starting at the specified offset, FROM the caller's
  123.     buffer. A maximum of size characters are overwritten to the value.  The function returns
  124.     the amount of data copied from the buffer to the value.
  125.     
  126.     Note, overwriting of global names is NOT allowed and assumed not passed to this routine.
  127.     Immediates are, however, handled and can be overwritten up to their existing size.
  128.     */
  129.     
  130.     
  131. CMBoolean cmConvertImmediate(struct TOCValue *theValue);
  132.     /*
  133.     This routine is called whenever an immediate data value must be converted to a
  134.     non-immediate.  It takes as parameters the pointer to the immediate value and returns
  135.     true if there are no errors.  On return the value will have been converted to a
  136.     non-immediate and the input segment CMValue changed to container the offset to the 
  137.     now written value.
  138.     */
  139.     
  140.     
  141. struct TOCValue *cmInsertNewSegment(struct TOCValueHdr *theValueHdr,
  142.                                                                          struct TOCValue *insBeforeValue,
  143.                                                                           CM_ULONG segOffset, CM_ULONG dataOffset,
  144.                                                                          CMSize size);
  145.     /*
  146.     This routine is called by CMInsertValueData() to create a new value segment insert to be
  147.     inserted into a previously existing value.  It is also called when applying data insert
  148.     updates at open time (by the internal routine applyValueUpdateInstructions() in 
  149.      Update.c ).  The new insert data is already written to the (updating) container, and the
  150.     data is at container offset dataOffset.  It is size bytes long.  The insert is to be at
  151.     the specified segOffset within the value segment insBeforeValue. 
  152.     
  153.     The function returns a pointer to the newly created insert segment, or NULL if there is
  154.     an error and the error reporter returns.
  155.  
  156.     Note, this routine is for non-immediate data insertions only.  CMInsertValueData() 
  157.     handles insertions on immediates.  For updating, immediates are handled differently and
  158.     thus can't get in here.
  159.     */
  160.     
  161.     
  162. void cmDeleteSegmentData(struct TOCValueHdr *theValueHdr, CM_ULONG startOffset,
  163.                                                  CM_ULONG endOffset);
  164.     /*
  165.     This routine is called by CMDeleteValueData() to delete value data  It is also called
  166.     when applying data deletion updates at open time (by the internal routine
  167.     applyValueUpdateInstructions() in  Update.c ).  All the data starting at offset 
  168.     startOffset, up to and including the end offset, endOffset, are to be deleted.  If the
  169.     start and end offsets span entire value segments, those segments are removed.
  170.  
  171.     Note, this routine is for non-immediate data deletions only.  CMDeleteValueData() handles
  172.     deletions on immediates.  For updating, immediates are handled differently and thus can't
  173.     get in here.
  174.     */
  175.     
  176.     
  177. struct TOCValueHdr *cmMoveValueHdr(struct TOCValueHdr *theFromValueHdr, CMObject object,
  178.                                                                                                                                                   CMProperty property);
  179.     /*
  180.     This routine is called by CMMoveValueData() to move a value (header).  It is also called
  181.     when applying "inserted" (move) updates at open time (by the internal routine
  182.     applyValueUpdateInstructions() in  Update.c ).   The value is physically deleted from its
  183.     original object/property as if a CMDeleteValue() were done on it.  If the value deleted
  184.     is the only one for the property, the property itself is deleted as in
  185.     CMDeleteObjectProperty(). 
  186.     
  187.     The value is added to the "to"s object propery in a manner similar to a CMNewValue(). The
  188.     order of the values for both the value's original object property and for the value's
  189.     new object property may be changed.
  190.  
  191.     Note, that although the effect of a move is a combination CMDeleteValue()/CMNewValue(),
  192.     THE INPUT REFNUM REMAINS VALID!  Its association is now with the new object property.
  193.  
  194.   The input refNum is returned as the function result.  NULL is returned if there is an 
  195.   error and the error reporter returns.
  196.     */
  197.     
  198.  
  199.                                                           CM_END_CFUNCTIONS
  200. #endif
  201.