home *** CD-ROM | disk | FTP | other *** search
/ Chip 1997 October / Chip_1997-10_cd.bin / tema / sybase / powerj / hpp.z / WDATASRC.HPP < prev    next >
C/C++ Source or Header  |  1997-01-23  |  19KB  |  590 lines
  1.  
  2. #ifndef _WDATASRC_HPP_INCLUDED
  3. #define _WDATASRC_HPP_INCLUDED
  4.  
  5. //-----------------------------------------------------------------------
  6. //
  7. // Interfaces used to implement the binding of objects to data sources.
  8. //
  9. // These interfaces are meant to be embedded in other objects.  All
  10. // methods are virtual so that specializations can be created.
  11. //
  12. //-----------------------------------------------------------------------
  13.  
  14. #ifndef _WDATAERR_HPP_INCLUDED
  15. #include "wdataerr.hpp"
  16. #endif
  17. #ifndef _WDATATRG_HPP_INCLUDED
  18. #include "wdatatrg.hpp"
  19. #endif
  20.  
  21. enum WDSMoveType {
  22.     WDSMoveNext     = SQL_FETCH_NEXT,
  23.     WDSMoveFirst    = SQL_FETCH_FIRST,
  24.     WDSMoveLast     = SQL_FETCH_LAST,
  25.     WDSMovePrevious = SQL_FETCH_PRIOR,
  26.     WDSMoveAbsolute = SQL_FETCH_ABSOLUTE,
  27.     WDSMoveRelative = SQL_FETCH_RELATIVE,
  28.     WDSMoveBookmark = SQL_FETCH_BOOKMARK
  29. };
  30.  
  31. enum WDSEditMode {
  32.     WDSEditModeRead,   // just reading
  33.     WDSEditModeEdit,   // editing current row
  34.     WDSEditModeAdd     // adding a new row
  35. };
  36.  
  37. //
  38. // Declare the classes for state information
  39. //
  40.  
  41. typedef void *WDataSourceState;
  42.  
  43. //
  44. // WDataSource -- An interface exposed by an object which has data
  45. //                that is to be bound to other objects.
  46. //
  47.  
  48. class WCMCLASS WDataSource : public WEventGenerator {
  49.  
  50.     private:
  51.  
  52.         WDataSource( const WDataSource & );
  53.         WDataSource& operator=( const WDataSource & );
  54.  
  55.     public:
  56.  
  57.         WDataSource();
  58.  
  59.         ~WDataSource();
  60.  
  61.         /*********************************************************
  62.          * Operators
  63.          *********************************************************/
  64.  
  65.         // operator[]
  66.  
  67.         const WDataColumn & operator[]( WShort i ) const;
  68.         const WDataColumn & operator[]( const WString & name ) const;
  69.  
  70.         /*********************************************************
  71.          * Properties
  72.          *********************************************************/
  73.  
  74.         // AlwaysReadWriteTargets
  75.         //
  76.         //    If TRUE, enables targets to be enabled for read and write 
  77.         //    even when the data source is read only
  78.  
  79.         virtual WBool GetAlwaysReadWriteTargets() const;
  80.         virtual WBool SetAlwaysReadWriteTargets( WBool enable );
  81.  
  82.         // AutoEdit
  83.         //
  84.         //    If TRUE, data targets will automatically engage edit mode
  85.         //    when their value is changed.
  86.  
  87.         virtual WBool GetAutoEdit() const;
  88.         virtual WBool SetAutoEdit( WBool autoEdit );
  89.  
  90.         // AutoRefresh
  91.         //
  92.         //    If TRUE, updates and deletes will appear immediately in any
  93.         //    attached data targets.
  94.  
  95.         virtual WBool GetAutoRefresh() const;
  96.         virtual WBool SetAutoRefresh( WBool autoRefresh );
  97.  
  98.         // BOF
  99.         //
  100.         //    Returns TRUE if the cursor is positioned before the
  101.         //    first row in the result set.
  102.  
  103.         virtual WBool GetBOF() const;
  104.  
  105.         // Bookmark
  106.         //
  107.         //    Returns an integer which is used as a bookmark for
  108.         //    the current row.  You can move to it using the MoveBookmark
  109.         //    method.
  110.  
  111.         virtual WDWord GetBookmark() const;
  112.  
  113.         // Column
  114.         //
  115.         //    Return a specific column, either by index (columns
  116.         //    start at 0) or by name.
  117.  
  118.         virtual const WDataColumn & GetColumn( WShort index ) const;
  119.         virtual const WDataColumn & GetColumn( const WString & name ) const;
  120.  
  121.         // ColumnCount
  122.         //
  123.         //    Return the number of columns available (note that column 0
  124.         //    is always a special column).
  125.  
  126.         virtual WShort GetColumnCount() const;
  127.  
  128.         // ColumnIndex
  129.         //
  130.         //    Return the index of a column given its name.  Returns -1
  131.         //    on error.
  132.  
  133.         virtual WShort GetColumnIndex( const WString & str ) const;
  134.  
  135.         // CurrentRow
  136.         //
  137.         //    The current row (rows start at 1), if known.
  138.  
  139.         virtual WLong GetCurrentRow() const;
  140.  
  141.         // EditMode
  142.         //
  143.         //    The current edit mode.
  144.  
  145.         virtual WDSEditMode GetEditMode() const;
  146.  
  147.         // EOF
  148.         //
  149.         //    Returns TRUE if the cursor is positioned after the
  150.         //    last row in the result set.
  151.  
  152.         virtual WBool GetEOF() const;
  153.  
  154.         // Empty
  155.         //
  156.         //    Returns TRUE if the result set is empty (no rows)
  157.         //    or null (no columns).
  158.  
  159.         virtual WBool GetEmpty() const;
  160.  
  161.         // ErrorCode
  162.         //
  163.         //    Returns the error code of the last operation.
  164.         //    Can optionally return a code specifying which driver
  165.         //    API was called (driver-specific).
  166.  
  167.         virtual WLong GetErrorCode( WLong *apiCode=NULL ) const;
  168.  
  169.         // ErrorList
  170.         //
  171.         //    Returns the list of errors from the last operation.
  172.  
  173.         virtual WDataErrorArray GetErrorList() const;
  174.  
  175.         // ForwardOnly
  176.         //
  177.         //    Returns TRUE if moves are only allowed in the forward
  178.         //    direction.
  179.  
  180.         virtual WBool GetForwardOnly() const;
  181.  
  182.         // Null
  183.         //
  184.         //    Returns TRUE if the result set is null (no columns).
  185.         //    This is NOT the same as an empty result set.
  186.  
  187.         virtual WBool GetNull() const;
  188.  
  189.         // Opened
  190.         //
  191.         //    Returns TRUE if the datasource is "open" (it has data).
  192.  
  193.         virtual WBool GetOpened() const;
  194.  
  195.         // RawData
  196.         //
  197.         //    Fetch data directly from the data source, bypassing
  198.         //    any binding that may have occurred.  Use this to get
  199.         //    chunks of data.
  200.  
  201.         virtual WBool GetRawData( WShort index, WNativeDataType type,
  202.                                   void *buffer, WLong bufferSize=0,
  203.                                   WLong *bytesRemaining=NULL ) const;
  204.  
  205.         // ReadOnly
  206.         //
  207.         //    If TRUE, no changes can be made to the data source.
  208.  
  209.         virtual WBool GetReadOnly() const;
  210.  
  211.         // RowChanged
  212.         //
  213.         //    If TRUE, one or more of the values in the row may need
  214.         //    to be updated.
  215.  
  216.         virtual WBool GetRowChanged() const;
  217.         virtual WBool SetRowChanged( WBool changed );
  218.  
  219.         // RowCount
  220.         //
  221.         //    Returns the number of rows.  This may be expensive to call,
  222.         //    as it may force rows to be counted one by one.  If you pass
  223.         //    in FALSE, it simply uses the last known row count value,
  224.         //    which may be -1 if the count is not yet known.
  225.         //    If you just need to know whether a result set is empty or null,
  226.         //    see the Empty and Null properties instead.
  227.  
  228.         virtual WLong GetRowCount( WBool forceCount=TRUE ) const;
  229.  
  230.         // RowTargetChanged
  231.         //
  232.         //    If TRUE, one or more of the values in the row
  233.         //    was changed but the data source is readonly
  234.  
  235.         virtual WBool GetRowTargetChanged() const;
  236.         virtual WBool SetRowTargetChanged( WBool changed );
  237.  
  238.         // TargetsEnabled
  239.         //
  240.         //    Enable or disable the targets.  Disabling does not do a
  241.         //    clear, merely prevents them from updating themselves.
  242.  
  243.         virtual WBool GetTargetsEnabled() const;
  244.         virtual WBool SetTargetsEnabled( WBool enabled );
  245.  
  246.         // ThreadSafe
  247.         //
  248.         //    If TRUE, the object can be accessed safely from different
  249.         //    threads and the ThreadLock/ThreadUnlock methods are enabled.
  250.  
  251.         virtual WBool GetThreadSafe() const;
  252.         virtual WBool SetThreadSafe( WBool safe );
  253.  
  254.         // Value
  255.         //
  256.         //    Set/get the value of a particular column in the
  257.         //    current row.  See RawData as well.
  258.  
  259.         virtual WDataValue GetValue( WShort index,
  260.                                      WNativeDataType type=SQL_C_DEFAULT ) const = 0;
  261.         virtual WBool      SetValue( WShort index, const WDataValue & val ) = 0;
  262.  
  263.         /*********************************************************
  264.          * Methods
  265.          *********************************************************/
  266.  
  267.         // Add
  268.         //
  269.         //    Prepare to add a new row.  Returns FALSE if there are no
  270.         //    updatable columns or the query is read-only.  After setting
  271.         //    the new values with SetValue, call Update to actually
  272.         //    add the new row.  Call CancelUpdate to cancel any pending
  273.         //    add.
  274.  
  275.         virtual WBool Add( WBool copyValues=FALSE, WBool append=FALSE,
  276.                            WBool copyIntoBuffer=FALSE );
  277.  
  278.         // CancelUpdate
  279.         //
  280.         //    Cancel a pending update or add operation.
  281.  
  282.         virtual WBool CancelUpdate( WBool notifyTargets=TRUE );
  283.  
  284.         // ClearTargets
  285.         //
  286.         //    Tell any targets to clear themselves.
  287.  
  288.         virtual WBool ClearTargets();
  289.  
  290.         // Close
  291.         //
  292.         //    Close the current query, if any.
  293.  
  294.         virtual WBool Close( WBool discardResults=TRUE,
  295.                              WBool isRequery=FALSE );
  296.  
  297.         // Delete
  298.         //
  299.         //    Deletes the current row.
  300.  
  301.         virtual WBool Delete( WBool triggerEvent=TRUE,
  302.                               WBool notifyTargets=TRUE );
  303.  
  304.         // Edit
  305.         //
  306.         //    Prepare the current row for editing.  Returns FALSE if
  307.         //    there are no updatable columns or the query is read-only.
  308.         //    After setting the new values with SetValue, call Update
  309.         //    to actually update the row.  Call CancelUpdate to cancel
  310.         //    any pending add.
  311.  
  312.         virtual WBool Edit();
  313.  
  314.         // MoreResults
  315.         //
  316.         //    Closes the current result set and opens the next
  317.         //    result set, if any.  Returns TRUE if a new result
  318.         //    set is available and open, FALSE otherwise.
  319.  
  320.         virtual WBool MoreResults();
  321.  
  322.         // Move
  323.         //
  324.         //    General move routine for navigating through the data
  325.         //    source.  By default does an absolute move.
  326.  
  327.         virtual WBool Move( WLong row, WBool notifyTargets=TRUE,
  328.                             WDSMoveType type=WDSMoveAbsolute,
  329.                             WBool triggerEvents=TRUE );
  330.  
  331.         // MoveBookmark
  332.         //
  333.         //    Move to a bookmark.
  334.  
  335.         WBool MoveBookmark( WDWord bookmark, WBool notify=TRUE,
  336.                             WBool triggerEvents=TRUE );
  337.  
  338.         // MoveFirst
  339.         //
  340.         //    Move to the first row.
  341.  
  342.         WBool MoveFirst( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  343.  
  344.         // MoveLast
  345.         //
  346.         //    Move to the last row.
  347.  
  348.         WBool MoveLast( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  349.  
  350.         // MoveNext
  351.         //
  352.         //    Move to the next row.
  353.  
  354.         WBool MoveNext( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  355.  
  356.         // MovePrevious
  357.         //
  358.         //    Move to the previous row.
  359.  
  360.         WBool MovePrevious( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  361.  
  362.         // MoveRelative
  363.         //
  364.         //    Move to a relative row.
  365.  
  366.         WBool MoveRelative( WLong offset, WBool notifyTargets=TRUE,
  367.                             WBool triggerEvents=TRUE );
  368.  
  369.         // Open
  370.         //
  371.         //    Execute the SQL statement and open the result set for
  372.         //    processing.
  373.  
  374.         virtual WBool Open( WBool executeStatement=TRUE,
  375.                             WBool isRequery=FALSE );
  376.  
  377.         // Refresh
  378.         //
  379.         //    Refresh (re-read) all of the data. The cursor is position is
  380.         //    retained if possible.
  381.  
  382.         virtual WBool Refresh();
  383.  
  384.         // RefreshTargets
  385.         //
  386.         //    Refresh the targets, causing them to re-read their values
  387.         //    for the current row.  Can optionally specify whether
  388.         //    multirow targets should reread all their values.
  389.  
  390.         virtual WBool RefreshTargets( WBool multiRow=FALSE );
  391.  
  392.         // RestoreState
  393.         //
  394.         //    Restore the data source's state to a previously saved
  395.         //    value.
  396.  
  397.         virtual WBool RestoreState( const WDataSourceState state,
  398.                                     WBool restore=TRUE );
  399.  
  400.         // SaveState
  401.         //
  402.         //    Save the state of a data source.  What gets saved
  403.         //    depends on the data source.  It might be a bookmark,
  404.         //    it might be much more.
  405.  
  406.         virtual WBool SaveState( WDataSourceState & state );
  407.  
  408.         // SearchUsingTargets
  409.         //
  410.         //    Do a search based on current target values.  How this
  411.         //    affects the result set is up to the data source.
  412.  
  413.         virtual WBool SearchUsingTargets();
  414.  
  415.         // ThreadLock
  416.         //
  417.         //    Lock access to the data source to the thread that
  418.         //    calls this function.  Can specify what to do if
  419.         //    the thread is already locked.  Note that once a
  420.         //    thread is locked care must be taken in calling
  421.         //    methods that may trigger events or notify targets,
  422.         //    since deadlock can occur.
  423.  
  424.         virtual WBool ThreadLock( WBool wait=TRUE, WDWord timeout=0xFFFFFFFF );
  425.  
  426.         // ThreadUnlock
  427.         //
  428.         //    Unlock the data source.  Returns TRUE if the source is no
  429.         //    longer locked (or was never locked) by the calling thread.
  430.  
  431.         virtual WBool ThreadUnlock();
  432.  
  433.         // Update
  434.         //
  435.         //    Update the row (either the current row or a row that is
  436.         //    being added) to the database.  Can optionally cause a
  437.         //    ValidateData event to be triggered.
  438.  
  439.         virtual WBool Update( WBool triggerEvent=TRUE,
  440.                               WBool notifyTargets=TRUE );
  441.  
  442.         /*********************************************************
  443.          * Other
  444.          *********************************************************/
  445.  
  446.         // DataAvailable
  447.         //
  448.         //    Call the DataAvailable method on all registered targets.
  449.  
  450.         virtual WBool DataAvailable( WLong row,
  451.                                      WULong reason,
  452.                                      WULong suggestedAction,
  453.                                      WBool multiValueOnly );
  454.  
  455.         // DataClose
  456.         //
  457.         //    Call the DataClose method on all registered targets.
  458.  
  459.         virtual WBool DataClose( WBool isRequery );
  460.  
  461.         // DataOpen
  462.         //
  463.         //    Call the DataOpen method on all registered targets.
  464.  
  465.         virtual WBool DataOpen( WBool isRequery );
  466.  
  467.         // DataRequest
  468.         //
  469.         //    Call the DataRequest method on all registered targets.
  470.  
  471.         virtual WBool DataRequest( WULong reason, WULong suggestedAction,
  472.                                    WBool touched=FALSE );
  473.  
  474.         // RemoveAllTargets
  475.         //
  476.         //    Call SetDataSource(NULL) on each target object.
  477.  
  478.         virtual WBool RemoveAllTargets();
  479.  
  480.         /*********************************************************
  481.          * Target Methods (only targets should call these)
  482.          *********************************************************/
  483.  
  484.         // AddTarget
  485.         //
  486.         //    DataTarget objects call this method to register themselves
  487.         //    with a data source.
  488.  
  489.         virtual WBool AddTarget( WDataTarget *target );
  490.  
  491.         // BindTarget
  492.         //
  493.         //    DataTarget objects call this method when processing a
  494.         //    DataOpen event to let the source know which columns
  495.         //    they are interested in.
  496.  
  497.         virtual WBool BindTarget( WDataTarget *target, WShort column,
  498.                                   WNativeDataType type=SQL_C_DEFAULT );
  499.  
  500.         // RemoveTarget
  501.         //
  502.         //    DataTarget objects call this method to deregister themselves.
  503.  
  504.         virtual WBool RemoveTarget( WDataTarget *target );
  505.  
  506.     public:
  507.  
  508.         wllist_header & GetTargetListHeader();
  509.         wllist_header & GetBindListHeader();
  510.         void            ClearBindList();
  511.  
  512.         WBool GetTargetRowExtents( WLong & firstRow, WLong & lastRow );
  513.  
  514.     protected:
  515.  
  516.         // List of registered targets...
  517.  
  518.         struct WTargetEntry {
  519.             wllist_link      link;
  520.             WDataTarget     *target;
  521.             WDataTargetType  type;
  522.             WShort           firstColumn; // first column bound to the control
  523.         };
  524.  
  525.         WTargetEntry *FindTarget( WDataTarget *target );
  526.         WBool         SortTargets();
  527.  
  528.         // List of binding suggestions...
  529.  
  530.         struct WBindEntry {
  531.             wllist_link      link;
  532.             WShort           column;
  533.             WDataTarget     *target;
  534.             WNativeDataType  type;
  535.         };
  536.  
  537.         wllist_header        _targetList;
  538.         wllist_header        _bindList;
  539.         WLong                _row;
  540.         WBool                _rowChanged;
  541.         WBool                _targetsEnabled;
  542.         WBool                _alwaysReadWriteTargets;
  543.         WBool                _rowTargetChanged;
  544. };
  545.  
  546. typedef WEventData WAdjustCursorEventData;
  547. typedef WEventData WFetchDataEventData;
  548. typedef WEventData WMoveCursorEventData;
  549. typedef WEventData WBeginFetchDataEventData;
  550. typedef WEventData WBeginMoveCursorEventData;
  551. typedef WEventData WQueryBusyEventData;
  552.  
  553. enum WDSValidateAction {
  554.     WDSVAMoveNext     = WDSMoveNext,
  555.     WDSVAMoveFirst    = WDSMoveFirst,
  556.     WDSVAMoveLast     = WDSMoveLast,
  557.     WDSVAMovePrevious = WDSMovePrevious,
  558.     WDSVAMoveAbsolute = WDSMoveAbsolute,
  559.     WDSVAMoveRelative = WDSMoveRelative,
  560.     WDSVAMoveBookmark = WDSMoveBookmark,
  561.     WDSVAUpdateCurrentRow,
  562.     WDSVAUpdateNewRow,
  563.     WDSVADeleteCurrentRow,
  564. };
  565.  
  566. struct WQueryOpenEventData : public WEventData {
  567.     WBool isRequery;
  568. };
  569.  
  570. struct WQueryCloseEventData : public WEventData {
  571.     WBool isRequery;
  572. };
  573.  
  574. struct WValidateDataEventData : public WEventData {
  575.     WDSValidateAction action;    // action about to happen
  576.     WLong             row;       // row data for action
  577.     WBool             cancel;    // set to TRUE to cancel the action
  578.     WBool             update;    // if TRUE, data is updated before move
  579.  
  580.     //
  581.     // Use when updatePolicy of query object is WQUPUserDefine.
  582.     //
  583.     // The user should set this to TRUE when successful update to the
  584.     // current row in the event handler has been done.
  585.     //
  586.     WBool             hasPerformUpdate;
  587. };
  588.  
  589. #endif
  590.