All Frameworks  Class Hierarchy  This Framework  Previous  Next  Indexes

System Interface CATIUExitCryptedILockBytes

System.IUnknown
  |
  +---System.CATILockBytes
    |
    +---CATIUExitCryptedILockBytes
 

Usage: you can freely reimplement this interface.


interface CATIUExitCryptedILockBytes

Interface to enable customer specific actions on files.
Role: This interface is a user exit, that allows a customer in particular to audit files usage, manage data integrity or data confidentiality for all files manipulated by the V5-code.
You should implement it on the CATUExitCryptedILockBytes component by creating a data extension. This interface inherits from CATILockBytes. When implementing the inheritated methods note that :

  1. All the given offsets and lengths are those of the document before taking any action. This is a key point in order to get a correct behaviour of the ReadAt and WriteAt methods with the V5 composite documents.
  2. The size returned by the Stat method must reflect the size of the document before taking any action. This means if your implementation is bufferized, that you must take into account the current physical size of the array and the size of the unflushed memory buffers. This size is used to determine where the next write can occur.
  3. In addition to the already defined in CATILockBytes error codes the reading and writing methods have to returned STG_E_DOCFILECORRUPT when the action has failed.
  4. From the methods that are not inheritated from CATILockBytes only Open and Close will be used for manipulating V5 documents.
  5. As the sharing mode of the array is specified in the Open, it is not necessary to implement the LockRegion and UnlockRegion.

  6. Method Index


    o Close()
    Closes the CATILockBytes.
    o Open(CATUnicodeString*,DWORD,CATSysOpenMode,CATSysSharing,CATSysCreateMode,CATSysCloseMode)
    Defines the way to open the CATILockbytes
    Role:Defines the way to open the CATILockBytes.
    o OpenW(CATUC2Bytes*,DWORD,CATSysOpenMode,CATSysSharing,CATSysCreateMode,CATSysCloseMode)
    Defines the way to open the CATILockbytes
    Role:Defines the way to open the CATILockBytes.
    o Read(void*,ULONG,ULONG*)
    Reads and retrieves a block of data.
    o ReadLine(char*,ULONG,int&)
    Reads in the file and returns a line.
    o ReadLineW(CATUnicodeString*,ULONG,int&)
    Reads in the file and returns a line of unicode characters.
    o ReadLineWchar(CATUC2Bytes*,ULONG,int&)
    Reads in the file and returns a line of unicode characters.
    o Write(void*,ULONG,ULONG*)
    Applies action and writes a block of data.
    o WriteLine(char*)
    Applies action and writes a line for text files.
    o WriteLineW(CATUnicodeString*)
    Applies action and writes a line of unicode characters.
    o WriteLineWchar(CATUC2Bytes*)
    Applies action and writes a line of unicode characters.

    Methods


    o Close
    public virtual HRESULT Close()= 0
    Closes the CATILockBytes.
    Role: Closes the CATILockBytes.
    Returns:
    Legal values:
    S_OK : on Success
    o Open
    public virtual HRESULT Open( const CATUnicodeString* iPath,
    DWORD iMode,
    CATSysOpenMode iOpenMode,
    CATSysSharing iSharingMode,
    CATSysCreateMode iOpenFlag,
    CATSysCloseMode iCloseFlag= CATSys_Close)=0
    Defines the way to open the CATILockbytes
    Role:Defines the way to open the CATILockBytes.
    Parameters:
    iMode
    The global opening mode used by the V5 documents. This mode is not to be analysed, but should be stored to be returned in the grfMode field of a STATSTG structure upon a call to the Stat method. For non V5-documents it will be 0 and never used.
    iOpenMode
    Opening mode
    iSharingMode
    Sharing mode
    iOpenFlag
    flag for specifying the open processing
    iSpecialFlag
    flag for specifying special behavior. Legal values:
    1 : the file is deleted on close.
    0 : Nothing
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_INVALIDNAME : invalid name for the document.
    STG_E_ACCESSDENIED: access to the document not granted.
    STG_E_LOCKVIOLATION : document locked by another process.
    STG_E_NOMOREFILES : too many opened files
    STG_E_INVALIDPARAMETER : arguments incorrect.
    STG_E_DOCFILECORRUPT : document can not be read.
    STG_E_FILENOTFOUND : document can not be found.
    STG_E_PATHNOTFOUND : The path of the document could not be found.
    STG_E_INSUFFICIENTMEMORY : no more memory to make the open.
    STG_E_DISKISWRITEPROTECTED: open in write impossible on a write-protected disk.
    STG_E_UNKNOWN : unexpected error.
    o OpenW
    public virtual HRESULT OpenW( const CATUC2Bytes* iPath,
    DWORD iMode,
    CATSysOpenMode iOpenMode,
    CATSysSharing iSharingMode,
    CATSysCreateMode iOpenFlag,
    CATSysCloseMode iCloseFlag= CATSys_Close)=0
    Defines the way to open the CATILockbytes
    Role:Defines the way to open the CATILockBytes. This method must be thread safe. The other open method with CATUnicodeString argument can not be used in a threading context.
    Parameters:
    iPath
    Pointer to the wide char string null terminated defining the path.
    iMode
    The global opening mode used by the V5 documents. This mode is not to be analysed, but should be stored to be returned in the grfMode field of a STATSTG structure upon a call to the Stat method. For non V5-documents it will be 0 and never used.
    iOpenMode
    Opening mode
    iSharingMode
    Sharing mode
    iOpenFlag
    flag for specifying the open processing
    iSpecialFlag
    flag for specifying special behavior. Legal values:
    1 : the file is deleted on close.
    0 : Nothing
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_INVALIDNAME : invalid name for the document.
    STG_E_ACCESSDENIED: access to the document not granted.
    STG_E_LOCKVIOLATION : document locked by another process.
    STG_E_NOMOREFILES : too many opened files
    STG_E_INVALIDPARAMETER : arguments incorrect.
    STG_E_DOCFILECORRUPT : document can not be read.
    STG_E_FILENOTFOUND : document can not be found.
    STG_E_PATHNOTFOUND : The path of the document could not be found.
    STG_E_INSUFFICIENTMEMORY : no more memory to make the open.
    STG_E_DISKISWRITEPROTECTED: open in write impossible on a write-protected disk.
    STG_E_UNKNOWN : unexpected error.
    o Read
    public virtual HRESULT Read(void* iBuff,
    ULONG iLengthToRead,
    ULONG* oLengthRead) = 0
    Reads and retrieves a block of data.
    Role: Reads a block of data in a ILockBytes from the current offset in the file and returns the intial data before action. This method will be only used for non V5 documents.
    Parameters:
    iBuff
    [in] Buffer where the modified data where will be stored.
    iLengthToRead
    [i] the size of of the requested data.
    oLengthRead
    [out] the actual length of read data.
    Returns:

    S_OK :on Success.
    STG_E_READFAULT : problem while reading.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DOCFILECORRUPT : document can not be retrieved.
    STG_E_UNKNOWN : unexpected error.
    o ReadLine
    public virtual HRESULT ReadLine(char* ioLine,
    ULONG iNb,
    int& oEof)=0
    Reads in the file and returns a line.
    Role: Reads in file and return data as before applying the action up to the number of bytes specified by iNb parameter minus 1, or until a new-line character and transfers that character to the ioLine parameter, or until it encounters an end-of-file condition. The method then build a CATUnicodeString. This method will never be called for V5 documents.
    Parameters:
    ioLine
    [inout] line Buffer of at least iNb size.
    iNb
    [i] max number of character to read.
    oEof[o]
    to indicate if the end of the file as been reached.
    1 : End of file has been reached. In this case the return is S_OK.
    0 : End of file has not been reached
    Returns:

    S_OK :on Success .
    STG_E_READFAULT : problem while reading.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DOCFILECORRUPT : document can not be retrieved.
    STG_E_UNKNOWN : unexpected error.
    o ReadLineW
    public virtual HRESULT ReadLineW(CATUnicodeString* ioLine,
    ULONG iNb,
    int& oEof)=0
    Reads in the file and returns a line of unicode characters.
    Role: Reads in file and return data as before applying the action up to the number of bytes specified by iNb parameter minus 1, or until a new-line character and transfers that character to the ioLine parameter, or until it encounters an end-of-file condition. The method then build a CATUnicodeString. This method will never be called for V5 documents.
    Parameters:
    ioLine
    [inout] line Buffer of at least iNb size.
    iNb
    [i] max number of character to read.
    oEof[o]
    to indicate if the end of the file as been reached.
    1 : End of file has been reached. In this case the return is S_OK.
    0 : End of file has not been reached
    Returns:

    S_OK :on Success .
    STG_E_READFAULT : problem while reading.
    STG_E_INVALIDPARAMETER : incorrect arguments.
    STG_E_DOCFILECORRUPT : document can not be retrieved.
    STG_E_UNKNOWN : unexpected error.
    o ReadLineWchar
    public virtual HRESULT ReadLineWchar(CATUC2Bytes* ioLine,
    ULONG iNb,
    int& oEof)=0
    Reads in the file and returns a line of unicode characters.
    Role: Reads in the file and return data as before applying the action up to the number of bytes specified by iNb parameter minus 1, or until a new-line character and transfers that character to the ioLine parameter, or until it encounters an end-of-file condition. This method will never be called for V5 documents.
    Parameters:
    ioLine
    [inout] line Buffer of at least iNb size.
    iNb
    [i] max number of character to read.
    oEof[o]
    to indicate if the end of the file as been reached.
    1 : End of file has been reached. In this case the return is S_OK.
    0 : End of file has not been reached
    Returns:

    S_OK :on Success .
    STG_E_READFAULT : problem while reading.
    STG_E_INVALIDPARAMETER : incorrect arguments.
    STG_E_DOCFILECORRUPT : document can not be retrieved.
    STG_E_UNKNOWN : unexpected error.
    o Write
    public virtual HRESULT Write( const void* iDataSource,
    ULONG iLengthToWrite,
    ULONG* LengthWritten) = 0
    Applies action and writes a block of data.
    Role: Writes a block of data at the current offset, after applying the action. This method will be only used for non V5 documents.
    Parameters:
    iDataSource
    [in] Buffer of not initial data to write.
    iLengthToWrite
    [in] the size of of the data to write.
    oLengthWriten
    [out] the actual length of written data. Should be equal to iLengthToWrite if no problem has occurred.
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_WRITEFAULT : problem while writing.
    STG_E_MEDIUMFULL : disk full error.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DISKISWRITEPROTECTED : disk write protected.
    STG_E_INVALIDFUNCTION: unable to apply action on data.
    STG_E_UNKNOWN : unexpected error.
    o WriteLine
    public virtual HRESULT WriteLine( const char* iBuff)=0
    Applies action and writes a line for text files.
    Role: Applies action and writes the null-terminated string pointed to by the iBuff parameter. The method does not apply action and write the terminating null character. This method will be only used for non V5 documents.
    Parameters:
    iBuff
    [in] initial Line to write.
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_WRITEFAULT : problem while writing.
    STG_E_MEDIUMFULL : disk full error.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DISKISWRITEPROTECTED : disk write protected.
    STG_E_INVALIDFUNCTION: unable to apply action on data.
    STG_E_UNKNOWN : unexpected error.
    o WriteLineW
    public virtual HRESULT WriteLineW( const CATUnicodeString* iBuff)=0
    Applies action and writes a line of unicode characters.
    Role: Applies action and writes the null-terminated string pointed to by the iBuff parameter. The method does not apply action and write the terminating null character. This method will be only used for non V5 documents.
    Parameters:
    iBuff
    [in] initial Line to write.
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_WRITEFAULT : problem while writing.
    STG_E_MEDIUMFULL : disk full error.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DISKISWRITEPROTECTED : disk write protected.
    STG_E_INVALIDFUNCTION: unable to apply action on data.
    STG_E_UNKNOWN : unexpected error.
    o WriteLineWchar
    public virtual HRESULT WriteLineWchar( const CATUC2Bytes* iBuff)=0
    Applies action and writes a line of unicode characters.
    Role: Applies action and writes the null-terminated string pointed to by the iBuff parameter. The method does not apply action and write the terminating null character. This method will be only used for non V5 documents.
    Parameters:
    iBuff
    [in] initial Line to write.
    Returns:
    Legal values:
    S_OK :on Success.
    STG_E_WRITEFAULT : problem while writing.
    STG_E_MEDIUMFULL : disk full error.
    STG_E_INVALIDPARAMETER : arguments incorrects.
    STG_E_DISKISWRITEPROTECTED : disk write protected.
    STG_E_INVALIDFUNCTION: unable to appliy action on data.
    STG_E_UNKNOWN : unexpected error.

    This object is included in the file: CATIUExitCryptedILockBytes.h
    If needed, your Imakefile.mk should include the module: JS0GROUP

    Copyright © 2003, Dassault Systèmes. All rights reserved.