home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 10 / ioProg_10.iso / soft / optima / hpp.z / WDATASRC.HPP < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-26  |  17.3 KB  |  564 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.         // RowChanged
  204.         //
  205.         //    If TRUE, one or more of the values in the row may need
  206.         //    to be updated.
  207.  
  208.         virtual WBool GetRowChanged() const;
  209.         virtual WBool SetRowChanged( WBool changed );
  210.  
  211.         // RowCount
  212.         //
  213.         //    Returns the number of rows.  This may be expensive to call,
  214.         //    as it may force rows to be counted one by one.  If you pass
  215.         //    in FALSE, it simply uses the last known row count value,
  216.         //    which may be -1 if the count is not yet known.
  217.         //    If you just need to know whether a result set is empty or null,
  218.         //    see the Empty and Null properties instead.
  219.  
  220.         virtual WLong GetRowCount( WBool forceCount=TRUE ) const;
  221.  
  222.         // TargetsEnabled
  223.         //
  224.         //    Enable or disable the targets.  Disabling does not do a
  225.         //    clear, merely prevents them from updating themselves.
  226.  
  227.         virtual WBool GetTargetsEnabled() const;
  228.         virtual WBool SetTargetsEnabled( WBool enabled );
  229.  
  230.         // ThreadSafe
  231.         //
  232.         //    If TRUE, the object can be accessed safely from different
  233.         //    threads and the ThreadLock/ThreadUnlock methods are enabled.
  234.  
  235.         virtual WBool GetThreadSafe() const;
  236.         virtual WBool SetThreadSafe( WBool safe );
  237.  
  238.         // Value
  239.         //
  240.         //    Set/get the value of a particular column in the
  241.         //    current row.  See RawData as well.
  242.  
  243.         virtual WDataValue GetValue( WShort index,
  244.                                      WNativeDataType type=SQL_C_DEFAULT ) const = 0;
  245.         virtual WBool      SetValue( WShort index, const WDataValue & val ) = 0;
  246.  
  247.         /*********************************************************
  248.          * Methods
  249.          *********************************************************/
  250.  
  251.         // Add
  252.         //
  253.         //    Prepare to add a new row.  Returns FALSE if there are no
  254.         //    updatable columns or the query is read-only.  After setting
  255.         //    the new values with SetValue, call Update to actually
  256.         //    add the new row.  Call CancelUpdate to cancel any pending
  257.         //    add.
  258.  
  259.         virtual WBool Add( WBool copyValues=FALSE, WBool append=FALSE,
  260.                            WBool copyIntoBuffer=FALSE );
  261.  
  262.         // CancelUpdate
  263.         //
  264.         //    Cancel a pending update or add operation.
  265.  
  266.         virtual WBool CancelUpdate( WBool notifyTargets=TRUE );
  267.  
  268.         // ClearTargets
  269.         //
  270.         //    Tell any targets to clear themselves.
  271.  
  272.         virtual WBool ClearTargets();
  273.  
  274.         // Close
  275.         //
  276.         //    Close the current query, if any.
  277.  
  278.         virtual WBool Close( WBool discardResults=TRUE,
  279.                              WBool isRequery=FALSE );
  280.  
  281.         // Delete
  282.         //
  283.         //    Deletes the current row.
  284.  
  285.         virtual WBool Delete( WBool triggerEvent=TRUE,
  286.                               WBool notifyTargets=TRUE );
  287.  
  288.         // Edit
  289.         //
  290.         //    Prepare the current row for editing.  Returns FALSE if
  291.         //    there are no updatable columns or the query is read-only.
  292.         //    After setting the new values with SetValue, call Update
  293.         //    to actually update the row.  Call CancelUpdate to cancel
  294.         //    any pending add.
  295.  
  296.         virtual WBool Edit();
  297.  
  298.         // MoreResults
  299.         //
  300.         //    Closes the current result set and opens the next
  301.         //    result set, if any.  Returns TRUE if a new result
  302.         //    set is available and open, FALSE otherwise.
  303.  
  304.         virtual WBool MoreResults();
  305.  
  306.         // Move
  307.         //
  308.         //    General move routine for navigating through the data
  309.         //    source.  By default does an absolute move.
  310.  
  311.         virtual WBool Move( WLong row, WBool notifyTargets=TRUE,
  312.                             WDSMoveType type=WDSMoveAbsolute,
  313.                             WBool triggerEvents=TRUE );
  314.  
  315.         // MoveBookmark
  316.         //
  317.         //    Move to a bookmark.
  318.  
  319.         WBool MoveBookmark( WDWord bookmark, WBool notify=TRUE,
  320.                             WBool triggerEvents=TRUE );
  321.  
  322.         // MoveFirst
  323.         //
  324.         //    Move to the first row.
  325.  
  326.         WBool MoveFirst( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  327.  
  328.         // MoveLast
  329.         //
  330.         //    Move to the last row.
  331.  
  332.         WBool MoveLast( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  333.  
  334.         // MoveNext
  335.         //
  336.         //    Move to the next row.
  337.  
  338.         WBool MoveNext( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  339.  
  340.         // MovePrevious
  341.         //
  342.         //    Move to the previous row.
  343.  
  344.         WBool MovePrevious( WBool notifyTargets=TRUE, WBool triggerEvents=TRUE );
  345.  
  346.         // MoveRelative
  347.         //
  348.         //    Move to a relative row.
  349.  
  350.         WBool MoveRelative( WLong offset, WBool notifyTargets=TRUE,
  351.                             WBool triggerEvents=TRUE );
  352.  
  353.         // Open
  354.         //
  355.         //    Execute the SQL statement and open the result set for
  356.         //    processing.
  357.  
  358.         virtual WBool Open( WBool executeStatement=TRUE,
  359.                             WBool isRequery=FALSE );
  360.  
  361.         // Refresh
  362.         //
  363.         //    Refresh (re-read) all of the data. The cursor is position is
  364.         //    retained if possible.
  365.  
  366.         virtual WBool Refresh();
  367.  
  368.         // RefreshTargets
  369.         //
  370.         //    Refresh the targets, causing them to re-read their values
  371.         //    for the current row.  Can optionally specify whether
  372.         //    multirow targets should reread all their values.
  373.  
  374.         virtual WBool RefreshTargets( WBool multiRow=FALSE );
  375.  
  376.         // RestoreState
  377.         //
  378.         //    Restore the data source's state to a previously saved
  379.         //    value.
  380.  
  381.         virtual WBool RestoreState( const WDataSourceState state,
  382.                                     WBool restore=TRUE );
  383.  
  384.         // SaveState
  385.         //
  386.         //    Save the state of a data source.  What gets saved
  387.         //    depends on the data source.  It might be a bookmark,
  388.         //    it might be much more.
  389.  
  390.         virtual WBool SaveState( WDataSourceState & state );
  391.  
  392.         // ThreadLock
  393.         //
  394.         //    Lock access to the data source to the thread that
  395.         //    calls this function.  Can specify what to do if
  396.         //    the thread is already locked.  Note that once a
  397.         //    thread is locked care must be taken in calling
  398.         //    methods that may trigger events or notify targets,
  399.         //    since deadlock can occur.
  400.  
  401.         virtual WBool ThreadLock( WBool wait=TRUE, WDWord timeout=0xFFFFFFFF );
  402.  
  403.         // ThreadUnlock
  404.         //
  405.         //    Unlock the data source.  Returns TRUE if the source is no
  406.         //    longer locked (or was never locked) by the calling thread.
  407.  
  408.         virtual WBool ThreadUnlock();
  409.  
  410.         // Update
  411.         //
  412.         //    Update the row (either the current row or a row that is
  413.         //    being added) to the database.  Can optionally cause a
  414.         //    ValidateData event to be triggered.
  415.  
  416.         virtual WBool Update( WBool triggerEvent=TRUE,
  417.                               WBool notifyTargets=TRUE );
  418.  
  419.         /*********************************************************
  420.          * Other
  421.          *********************************************************/
  422.  
  423.         // DataAvailable
  424.         //
  425.         //    Call the DataAvailable method on all registered targets.
  426.  
  427.         virtual WBool DataAvailable( WLong row,
  428.                                      WULong reason,
  429.                                      WULong suggestedAction,
  430.                                      WBool multiValueOnly );
  431.  
  432.         // DataClose
  433.         //
  434.         //    Call the DataClose method on all registered targets.
  435.  
  436.         virtual WBool DataClose( WBool isRequery );
  437.  
  438.         // DataOpen
  439.         //
  440.         //    Call the DataOpen method on all registered targets.
  441.  
  442.         virtual WBool DataOpen( WBool isRequery );
  443.  
  444.         // DataRequest
  445.         //
  446.         //    Call the DataRequest method on all registered targets.
  447.  
  448.         virtual WBool DataRequest( WULong reason, WULong suggestedAction );
  449.  
  450.         // RemoveAllTargets
  451.         //
  452.         //    Call SetDataSource(NULL) on each target object.
  453.  
  454.         virtual WBool RemoveAllTargets();
  455.  
  456.         /*********************************************************
  457.          * Target Methods (only targets should call these)
  458.          *********************************************************/
  459.  
  460.         // AddTarget
  461.         //
  462.         //    DataTarget objects call this method to register themselves
  463.         //    with a data source.
  464.  
  465.         virtual WBool AddTarget( WDataTarget *target );
  466.  
  467.         // BindTarget
  468.         //
  469.         //    DataTarget objects call this method when processing a
  470.         //    DataOpen event to let the source know which columns
  471.         //    they are interested in.
  472.  
  473.         virtual WBool BindTarget( WDataTarget *target, WShort column,
  474.                                   WNativeDataType type=SQL_C_DEFAULT );
  475.  
  476.         // RemoveTarget
  477.         //
  478.         //    DataTarget objects call this method to deregister themselves.
  479.  
  480.         virtual WBool RemoveTarget( WDataTarget *target );
  481.  
  482.     public:
  483.  
  484.         wllist_header & GetTargetListHeader();
  485.         wllist_header & GetBindListHeader();
  486.         void            ClearBindList();
  487.  
  488.         WBool GetTargetRowExtents( WLong & firstRow, WLong & lastRow );
  489.  
  490.     protected:
  491.  
  492.         // List of registered targets...
  493.  
  494.         struct WTargetEntry {
  495.             wllist_link      link;
  496.             WDataTarget     *target;
  497.             WDataTargetType  type;
  498.             WShort           firstColumn; // first column bound to the control
  499.         };
  500.  
  501.         WTargetEntry *FindTarget( WDataTarget *target );
  502.         WBool         SortTargets();
  503.  
  504.         // List of binding suggestions...
  505.  
  506.         struct WBindEntry {
  507.             wllist_link      link;
  508.             WShort           column;
  509.             WDataTarget     *target;
  510.             WNativeDataType  type;
  511.         };
  512.  
  513.         wllist_header        _targetList;
  514.         wllist_header        _bindList;
  515.         WLong                _row;
  516.         WBool                _rowChanged;
  517.         WBool                _targetsEnabled;
  518. };
  519.  
  520. typedef WEventData WAdjustCursorEventData;
  521. typedef WEventData WFetchDataEventData;
  522. typedef WEventData WMoveCursorEventData;
  523. typedef WEventData WBeginFetchDataEventData;
  524. typedef WEventData WBeginMoveCursorEventData;
  525. typedef WEventData WQueryBusyEventData;
  526.  
  527. enum WDSValidateAction {
  528.     WDSVAMoveNext     = WDSMoveNext,
  529.     WDSVAMoveFirst    = WDSMoveFirst,
  530.     WDSVAMoveLast     = WDSMoveLast,
  531.     WDSVAMovePrevious = WDSMovePrevious,
  532.     WDSVAMoveAbsolute = WDSMoveAbsolute,
  533.     WDSVAMoveRelative = WDSMoveRelative,
  534.     WDSVAMoveBookmark = WDSMoveBookmark,
  535.     WDSVAUpdateCurrentRow,
  536.     WDSVAUpdateNewRow,
  537.     WDSVADeleteCurrentRow,
  538. };
  539.  
  540. struct WQueryOpenEventData : public WEventData {
  541.     WBool isRequery;
  542. };
  543.  
  544. struct WQueryCloseEventData : public WEventData {
  545.     WBool isRequery;
  546. };
  547.  
  548. struct WValidateDataEventData : public WEventData {
  549.     WDSValidateAction action;    // action about to happen
  550.     WLong             row;       // row data for action
  551.     WBool             cancel;    // set to TRUE to cancel the action
  552.     WBool             update;    // if TRUE, data is updated before move
  553.  
  554.     //
  555.     // Use when updatePolicy of query object is WQUPUserDefine.
  556.     //
  557.     // The user should set this to TRUE when successful update to the
  558.     // current row in the event handler has been done.
  559.     //
  560.     WBool             hasPerformUpdate;
  561. };
  562.  
  563. #endif
  564.