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