home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / com / tutsamp / stoclien / sink.cpp < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-05  |  18.2 KB  |  566 lines
  1. /*+==========================================================================
  2.   File:      SINK.CPP
  3.  
  4.   Summary:   Implementation file for the COPaperSink COM Object Class.
  5.              Connectable object notifications are handled by COPaperSink.
  6.  
  7.              COPaperSink offers a main IUnknown interface and the custom
  8.              IPaperSink interface (with the drawing Paper related event
  9.              features). This multiple interface COM Object Class is
  10.              achieved via the technique of nested classes.  The
  11.              implementation of the IPaperSink interface is nested inside
  12.              the COPaperSink Class.
  13.  
  14.              For a comprehensive tutorial code tour of this module's
  15.              contents and offerings see the tutorial STOCLIEN.HTM
  16.              file. For more specific technical details on the internal
  17.              workings see the comments dispersed throughout the module's
  18.              source code.
  19.  
  20.   Classes:   COPaperSink.
  21.  
  22.   Functions: none.
  23.  
  24.   Origin:    6-10-96: atrent - Editor-inheritance from BALL.CPP in
  25.              the CONSERVE Tutorial Code Sample.
  26.  
  27. ----------------------------------------------------------------------------
  28.   This file is part of the Microsoft COM Tutorial Code Samples.
  29.  
  30.   Copyright (C) Microsoft Corporation, 1997.  All rights reserved.
  31.  
  32.   This source code is intended only as a supplement to Microsoft
  33.   Development Tools and/or on-line documentation.  See these other
  34.   materials for detailed information regarding Microsoft code samples.
  35.  
  36.   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  37.   KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  38.   IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
  39.   PARTICULAR PURPOSE.
  40. ==========================================================================+*/
  41.  
  42.  
  43. /*---------------------------------------------------------------------------
  44.   We include WINDOWS.H for all Win32 applications.
  45.   We include OLE2.H because we will be calling the COM/OLE Libraries.
  46.   We include OLECTL.H because it has definitions for connectable objects.
  47.   We include APPUTIL.H because we will be building this application using
  48.     the convenient Virtual Window and Dialog classes and other
  49.     utility functions in the APPUTIL Library (ie, APPUTIL.LIB).
  50.   We include IPAPER.H and PAPGUIDS.H for the common paper-related
  51.     Interface class, GUID, and CLSID specifications.
  52.   We include PAPFILE.H because it has the C++ class used for compound file
  53.     storage of drawing paper data.
  54.   We include GUIPAPER.H because it declares the class for the main C++
  55.     object that can service the Sink events.
  56.   We include SINK.H because it has the class COPaperSink declarations.
  57. ---------------------------------------------------------------------------*/
  58. #include <windows.h>
  59. #include <ole2.h>
  60. #include <olectl.h>
  61. #include <apputil.h>
  62. #include <ipaper.h>
  63. #include <papguids.h>
  64. #include "papfile.h"
  65. #include "guipaper.h"
  66. #include "sink.h"
  67.  
  68.  
  69. /*---------------------------------------------------------------------------
  70.   COPaperSink's implementation of its main COM object class including
  71.   Constructor, Destructor, QueryInterface, AddRef, and Release.
  72. ---------------------------------------------------------------------------*/
  73.  
  74. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  75.   Method:   COPaperSink::COPaperSink
  76.  
  77.   Summary:  COPaperSink Constructor. Note the member initializer:
  78.             "m_ImpIPaperSink(this, pUnkOuter)" which is used to pass the
  79.             'this' and pUnkOuter pointers of this constructor function to
  80.             the constructor in the instantiation of the implementation of
  81.             the CImpIPaperSink interface (which is nested inside this
  82.             present COPaperSink Object Class).
  83.  
  84.   Args:     IUnknown* pUnkOuter,
  85.               Pointer to the the outer Unknown.  NULL means this COM Object
  86.               is not being Aggregated.  Non NULL means it is being created
  87.               on behalf of an outside COM object that is reusing it via
  88.               aggregation.
  89.             CGuiPaper* pGuiPaper)
  90.               Pointer to the main C++ object that can service the PaperSink
  91.               events.
  92.  
  93.   Modifies: m_cRefs, m_pUnkOuter, m_pGuiPaper.
  94.  
  95.   Returns:  void
  96. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  97. COPaperSink::COPaperSink(
  98.   IUnknown* pUnkOuter,
  99.   CGuiPaper* pGuiPaper) :
  100.   m_ImpIPaperSink(this, pUnkOuter)
  101. {
  102.   // Zero the COM object's reference count.
  103.   m_cRefs = 0;
  104.  
  105.   // No AddRef necessary if non-NULL, as we're nested.
  106.   m_pUnkOuter = pUnkOuter;
  107.  
  108.   // Assign the pointer to the Sink service C++ object.
  109.   m_pGuiPaper = pGuiPaper;
  110.  
  111.   return;
  112. }
  113.  
  114.  
  115. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  116.   Method:   COPaperSink::~COPaperSink
  117.  
  118.   Summary:  COPaperSink Destructor.
  119.  
  120.   Args:     void
  121.  
  122.   Returns:  void
  123. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  124. COPaperSink::~COPaperSink(void)
  125. {
  126.   return;
  127. }
  128.  
  129.  
  130. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  131.   Method:   COPaperSink::QueryInterface
  132.  
  133.   Summary:  QueryInterface of the COPaperSink non-delegating
  134.             IUnknown implementation.
  135.  
  136.   Args:     REFIID riid,
  137.               [in] GUID of the Interface being requested.
  138.             PPVOID ppv)
  139.               [out] Address of the caller's pointer variable that will
  140.               receive the requested interface pointer.
  141.  
  142.   Returns:  HRESULT
  143. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  144. STDMETHODIMP COPaperSink::QueryInterface(
  145.                REFIID riid,
  146.                PPVOID ppv)
  147. {
  148.   HRESULT hr = E_NOINTERFACE;
  149.  
  150.   *ppv = NULL;
  151.  
  152.   if (IID_IUnknown == riid)
  153.     *ppv = this;
  154.   else if (IID_IPaperSink == riid)
  155.     *ppv = &m_ImpIPaperSink;
  156.  
  157.   if (NULL != *ppv)
  158.   {
  159.     // We've handed out a pointer to the interface so obey the COM rules
  160.     // and AddRef the reference count.
  161.     ((LPUNKNOWN)*ppv)->AddRef();
  162.     hr = NOERROR;
  163.   }
  164.  
  165.  
  166.   return (hr);
  167. }
  168.  
  169.  
  170. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  171.   Method:   COPaperSink::AddRef
  172.  
  173.   Summary:  AddRef of the COPaperSink non-delegating IUnknown
  174.             implementation.
  175.  
  176.   Args:     void
  177.  
  178.   Modifies: m_cRefs.
  179.  
  180.   Returns:  ULONG
  181.               New value of m_cRefs (COM object's reference count).
  182. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  183. STDMETHODIMP_(ULONG) COPaperSink::AddRef(void)
  184. {
  185.   ULONG cRefs;
  186.  
  187.   cRefs = ++m_cRefs;
  188.  
  189.   return cRefs;
  190. }
  191.  
  192.  
  193. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  194.   Method:   COPaperSink::Release
  195.  
  196.   Summary:  Release of the COPaperSink non-delegating IUnknown
  197.             implementation.
  198.  
  199.   Args:     void
  200.  
  201.   Modifies: m_cRefs.
  202.  
  203.   Returns:  ULONG
  204.               New value of m_cRefs (COM object's reference count).
  205. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  206. STDMETHODIMP_(ULONG) COPaperSink::Release(void)
  207. {
  208.   ULONG cRefs;
  209.  
  210.   cRefs = --m_cRefs;
  211.  
  212.   if (0 == cRefs)
  213.   {
  214.     // We artificially bump the main ref count to prevent reentrancy
  215.     // via the main object destructor.  Not really needed in this
  216.     // COPaperSink but a good practice because we are aggregatable and
  217.     // may at some point in the future add something entertaining like
  218.     // some Releases to the COPaperSink destructor.
  219.     m_cRefs++;
  220.     delete this;
  221.   }
  222.  
  223.   return cRefs;
  224. }
  225.  
  226.  
  227. /*---------------------------------------------------------------------------
  228.   COPaperSink's nested implementation of the IPaperSink interface
  229.   including Constructor, Destructor, QueryInterface, AddRef, Release,
  230.   Locked, Unlocked, Loaded, Saved, InkStart, InkDraw, InkStop, Erased,
  231.   and Resized. Methods in this interface are called by COM objects on
  232.   the server side to send notifications to the client.
  233. ---------------------------------------------------------------------------*/
  234.  
  235. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  236.   Method:   COPaperSink::CImpIPaperSink::CImpIPaperSink
  237.  
  238.   Summary:  Constructor for the CImpIPaperSink interface instantiation.
  239.  
  240.   Args:     COPaperSink* pBackObj,
  241.               Back pointer to the parent outer object.
  242.             IUnknown* pUnkOuter
  243.               Pointer to the outer Unknown.  For delegation.
  244.  
  245.   Modifies: m_pBackObj, m_pUnkOuter.
  246.  
  247.   Returns:  void
  248. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  249. COPaperSink::CImpIPaperSink::CImpIPaperSink(
  250.   COPaperSink* pBackObj,
  251.   IUnknown* pUnkOuter)
  252. {
  253.   // Init the Back Object Pointer to point to the parent object.
  254.   m_pBackObj = pBackObj;
  255.  
  256.   // Init the CImpIPaperSink interface's delegating Unknown pointer.  We
  257.   // use the Back Object pointer for IUnknown delegation here if we are
  258.   // not being aggregated.  If we are being aggregated we use the supplied
  259.   // pUnkOuter for IUnknown delegation.  In either case the pointer
  260.   // assignment requires no AddRef because the CImpIPaperSink lifetime is
  261.   // quaranteed by the lifetime of the parent object in which
  262.   // CImpIPaperSink is nested.
  263.   if (NULL == pUnkOuter)
  264.     m_pUnkOuter = pBackObj;
  265.   else
  266.     m_pUnkOuter = pUnkOuter;
  267.  
  268.   return;
  269. }
  270.  
  271.  
  272. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  273.   Method:   COPaperSink::CImpIPaperSink::~CImpIPaperSink
  274.  
  275.   Summary:  Destructor for the CImpIPaperSink interface instantiation.
  276.  
  277.   Args:     void
  278.  
  279.   Returns:  void
  280. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  281. COPaperSink::CImpIPaperSink::~CImpIPaperSink(void)
  282. {
  283.   return;
  284. }
  285.  
  286.  
  287. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  288.   Method:   COPaperSink::CImpIPaperSink::QueryInterface
  289.  
  290.   Summary:  The QueryInterface IUnknown member of this IPaperSink interface
  291.             implementation that delegates to m_pUnkOuter, whatever it is.
  292.  
  293.   Args:     REFIID riid,
  294.               [in] GUID of the Interface being requested.
  295.             PPVOID ppv)
  296.               [out] Address of the caller's pointer variable that will
  297.               receive the requested interface pointer.
  298.  
  299.   Returns:  HRESULT
  300.               Returned by the delegated outer QueryInterface call.
  301. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  302. STDMETHODIMP COPaperSink::CImpIPaperSink::QueryInterface(
  303.                REFIID riid,
  304.                PPVOID ppv)
  305. {
  306.   // Delegate this call to the outer object's QueryInterface.
  307.   return m_pUnkOuter->QueryInterface(riid, ppv);
  308. }
  309.  
  310.  
  311. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  312.   Method:   COPaperSink::CImpIPaperSink::AddRef
  313.  
  314.   Summary:  The AddRef IUnknown member of this IPaperSink interface
  315.             implementation that delegates to m_pUnkOuter, whatever it is.
  316.  
  317.   Args:     void
  318.  
  319.   Returns:  ULONG
  320.               Returned by the delegated outer AddRef call.
  321. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  322. STDMETHODIMP_(ULONG) COPaperSink::CImpIPaperSink::AddRef(void)
  323. {
  324.   // Delegate this call to the outer object's AddRef.
  325.   return m_pUnkOuter->AddRef();
  326. }
  327.  
  328.  
  329. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  330.   Method:   COPaperSink::CImpIPaperSink::Release
  331.  
  332.   Summary:  The Release IUnknown member of this IPaperSink interface
  333.             implementation that delegates to m_pUnkOuter, whatever it is.
  334.  
  335.   Args:     void
  336.  
  337.   Returns:  ULONG
  338.               Returned by the delegated outer Release call.
  339. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  340. STDMETHODIMP_(ULONG) COPaperSink::CImpIPaperSink::Release(void)
  341. {
  342.   // Delegate this call to the outer object's Release.
  343.   return m_pUnkOuter->Release();
  344. }
  345.  
  346.  
  347. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  348.   Method:   COPaperSink::CImpIPaperSink::Locked
  349.  
  350.   Summary:  The COPaper object was locked by a client.
  351.  
  352.   Args:     void
  353.  
  354.   Returns:  HRESULT
  355.               Standard result code. NOERROR for success.
  356. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  357. STDMETHODIMP COPaperSink::CImpIPaperSink::Locked(
  358.                void)
  359. {
  360.   HRESULT hr = E_NOTIMPL;
  361.  
  362.   // For future evolution.
  363.  
  364.   return hr;
  365. }
  366.  
  367.  
  368. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  369.   Method:   COPaperSink::CImpIPaperSink::Unlocked
  370.  
  371.   Summary:  The COPaper object was Unlocked by a client.
  372.  
  373.   Args:     void
  374.  
  375.   Returns:  HRESULT
  376.               Standard result code. NOERROR for success.
  377. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  378. STDMETHODIMP COPaperSink::CImpIPaperSink::Unlocked(
  379.                void)
  380. {
  381.   HRESULT hr = E_NOTIMPL;
  382.  
  383.   // For future evolution.
  384.  
  385.   return hr;
  386. }
  387.  
  388.  
  389. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  390.   Method:   COPaperSink::CImpIPaperSink::Loaded
  391.  
  392.   Summary:  The COPaper object's ink drawing data was loaded from a
  393.             client's compound file.
  394.  
  395.   Args:     void
  396.  
  397.   Returns:  HRESULT
  398.               Standard result code. NOERROR for success.
  399. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  400. STDMETHODIMP COPaperSink::CImpIPaperSink::Loaded(
  401.                void)
  402. {
  403.   HRESULT hr;
  404.  
  405.   // We have been notified that a load was done. Thus, a whole new array
  406.   // of ink data must be displayed in a cleared window of this client.
  407.   m_pBackObj->m_pGuiPaper->ClearWin();
  408.   hr = m_pBackObj->m_pGuiPaper->PaintWin();
  409.  
  410.   return hr;
  411. }
  412.  
  413.  
  414. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  415.   Method:   COPaperSink::CImpIPaperSink::Saved
  416.  
  417.   Summary:  The COPaper object's drawing paper data was saved to a
  418.             client's compound file.
  419.  
  420.   Args:     void
  421.  
  422.   Returns:  HRESULT
  423.               Standard result code. NOERROR for success.
  424. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  425. STDMETHODIMP COPaperSink::CImpIPaperSink::Saved(
  426.                void)
  427. {
  428.   HRESULT hr = E_NOTIMPL;
  429.  
  430.   // For future evolution.
  431.  
  432.   return hr;
  433. }
  434.  
  435.  
  436. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  437.   Method:   COPaperSink::CImpIPaperSink::InkStart
  438.  
  439.   Summary:  Client is being told to start a display ink drawing sequence.
  440.  
  441.   Args:     SHORT nX,
  442.               X coordinate of the start point.
  443.             SHORT nY,
  444.               Y coordinate of the start point.
  445.             SHORT nWidth,
  446.               Ink Width in pixels.
  447.             COLORREF crInkColor)
  448.               RGB Ink color to be used in the subsequent inking sequence.
  449.  
  450.   Returns:  HRESULT
  451.               Standard result code. NOERROR for success.
  452. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  453. STDMETHODIMP COPaperSink::CImpIPaperSink::InkStart(
  454.                                             SHORT nX,
  455.                                             SHORT nY,
  456.                                             SHORT nWidth,
  457.                                             COLORREF crInkColor)
  458. {
  459.   // Turn off ink saving to the COPaper object.
  460.   m_pBackObj->m_pGuiPaper->InkSaving(FALSE);
  461.  
  462.   // Play the data back to the CGuiPaper for display only.
  463.   m_pBackObj->m_pGuiPaper->InkWidth(nWidth);
  464.   m_pBackObj->m_pGuiPaper->InkColor(crInkColor);
  465.   m_pBackObj->m_pGuiPaper->InkStart(nX, nY);
  466.  
  467.   return NOERROR;
  468. }
  469.  
  470.  
  471. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  472.   Method:   COPaperSink::CImpIPaperSink::InkDraw
  473.  
  474.   Summary:  Client is being told to draw/display ink drawing sequence data.
  475.  
  476.   Args:     SHORT nX,
  477.               X coordinate of the start point.
  478.             SHORT nY,
  479.               Y coordinate of the start point.
  480.  
  481.   Returns:  HRESULT
  482.               Standard result code. NOERROR for success.
  483. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  484. STDMETHODIMP COPaperSink::CImpIPaperSink::InkDraw(
  485.                                             SHORT nX,
  486.                                             SHORT nY)
  487. {
  488.   // Play the data back to the CGuiPaper for display only.
  489.   m_pBackObj->m_pGuiPaper->InkDraw(nX, nY);
  490.  
  491.   return NOERROR;
  492. }
  493.  
  494.  
  495. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  496.   Method:   COPaperSink::CImpIPaperSink::InkStop
  497.  
  498.   Summary:  Client is being told to stop an ink drawing sequence.
  499.  
  500.   Args:     SHORT nX,
  501.               X coordinate of the start point.
  502.             SHORT nY,
  503.               Y coordinate of the start point.
  504.  
  505.   Returns:  HRESULT
  506.               Standard result code. NOERROR for success.
  507. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  508. STDMETHODIMP COPaperSink::CImpIPaperSink::InkStop(
  509.                                             SHORT nX,
  510.                                             SHORT nY)
  511. {
  512.   // Stop the play of the data back to the CGuiPaper for display.
  513.   m_pBackObj->m_pGuiPaper->InkStop(nX, nY);
  514.  
  515.   // Turn Ink Data saving back on.
  516.   m_pBackObj->m_pGuiPaper->InkSaving(TRUE);
  517.  
  518.   return NOERROR;
  519. }
  520.  
  521.  
  522. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  523.   Method:   COPaperSink::CImpIPaperSink::Erased
  524.  
  525.   Summary:  The COPaper object's drawing paper data was erased by a client.
  526.  
  527.   Args:     void
  528.  
  529.   Returns:  HRESULT
  530.               Standard result code. NOERROR for success.
  531. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  532. STDMETHODIMP COPaperSink::CImpIPaperSink::Erased(
  533.                void)
  534. {
  535.   HRESULT hr = E_NOTIMPL;
  536.  
  537.   // For future evolution.
  538.  
  539.   return hr;
  540. }
  541.  
  542.  
  543. /*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  544.   Method:   COPaperSink::CImpIPaperSink::Resized
  545.  
  546.   Summary:  The COPaper object's drawing rectangle was resized by a client.
  547.  
  548.   Args:     SHORT nWidth,
  549.               Rectangle width in pixels.
  550.             SHORT nHeight)
  551.               Rectangle height in pixels.
  552.  
  553.   Returns:  HRESULT
  554.               Standard result code. NOERROR for success.
  555. M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
  556. STDMETHODIMP COPaperSink::CImpIPaperSink::Resized(
  557.                SHORT nWidth,
  558.                SHORT nHeight)
  559. {
  560.   HRESULT hr = E_NOTIMPL;
  561.  
  562.   // For future evolution.
  563.  
  564.   return hr;
  565. }
  566.