VirtualBox

Changeset 73939 in vbox for trunk/include/VBox/HostServices


Ignore:
Timestamp:
Aug 29, 2018 7:56:40 AM (6 years ago)
Author:
vboxsync
Message:

DnD/HostService: Renaming, docs.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/HostServices/Service.h

    r69107 r73939  
    44
    55/*
    6  * Copyright (C) 2011-2017 Oracle Corporation
     6 * Copyright (C) 2011-2018 Oracle Corporation
    77 *
    88 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    4040{
    4141
     42/**
     43 * Message class encapsulating HGCM parameters.
     44 */
    4245class Message
    4346{
    44     /* Contains a copy of HGCM parameters. */
    4547public:
     48
    4649    Message(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[])
    4750        : m_uMsg(0)
    … …  
    5760    }
    5861
    59     uint32_t message() const { return m_uMsg; }
    60     uint32_t paramsCount() const { return m_cParms; }
    61 
    62     int getData(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[]) const
     62    /**
     63     * Returns the type of this message.
     64     *
     65     * @returns Message type
     66     */
     67    uint32_t GetType(void) const { return m_uMsg; }
     68
     69    /**
     70     * Returns the parameter count of this message.
     71     *
     72     * @returns Parameter count.
     73     */
     74    uint32_t GetParamCount(void) const { return m_cParms; }
     75
     76    /**
     77     * Retrieves the raw HGCM parameter data
     78     *
     79     * @returns IPRT status code.
     80     * @param   uMsg            Message type to retrieve the parameter data for. Needed for sanity.
     81     * @param   cParms          Size (in parameters) of @a aParms array.
     82     * @param   aParms          Where to store the HGCM parameter data.
     83     */
     84    int GetData(uint32_t uMsg, uint32_t cParms, VBOXHGCMSVCPARM aParms[]) const
    6385    {
    6486        if (m_uMsg != uMsg)
    6587        {
    66             LogFlowFunc(("Message type does not match (%RU32 (buffer), %RU32 (guest))\n", m_uMsg, uMsg));
     88            LogFlowFunc(("Stored message type (%RU32) does not match request (%RU32)\n", m_uMsg, uMsg));
    6789            return VERR_INVALID_PARAMETER;
    6890        }
    6991        if (m_cParms > cParms)
    7092        {
    71             LogFlowFunc(("Parameter count does not match (%RU32 (buffer), %RU32 (guest))\n", m_cParms, cParms));
     93            LogFlowFunc(("Stored parameter count (%RU32) exceeds request buffer (%RU32)\n", m_cParms, cParms));
    7294            return VERR_INVALID_PARAMETER;
    7395        }
    … …  
    7698    }
    7799
    78     int getParmU32Info(uint32_t iParm, uint32_t *pu32Info) const
     100    /**
     101     * Retrieves a specific parameter value as uint32_t.
     102     *
     103     * @returns IPRT status code.
     104     * @param   uParm           Index of parameter to retrieve.
     105     * @param   pu32Info        Where to store the parameter value.
     106     */
     107    int GetParmU32(uint32_t uParm, uint32_t *pu32Info) const
    79108    {
    80109        AssertPtrNullReturn(pu32Info, VERR_INVALID_PARAMETER);
    81         AssertReturn(iParm < m_cParms, VERR_INVALID_PARAMETER);
    82         AssertReturn(m_paParms[iParm].type == VBOX_HGCM_SVC_PARM_32BIT, VERR_INVALID_PARAMETER);
    83 
    84         *pu32Info = m_paParms[iParm].u.uint32;
     110        AssertReturn(uParm < m_cParms, VERR_INVALID_PARAMETER);
     111        AssertReturn(m_paParms[uParm].type == VBOX_HGCM_SVC_PARM_32BIT, VERR_INVALID_PARAMETER);
     112
     113        *pu32Info = m_paParms[uParm].u.uint32;
    85114
    86115        return VINF_SUCCESS;
    87116    }
    88117
    89     int getParmU64Info(uint32_t iParm, uint64_t *pu64Info) const
     118    /**
     119     * Retrieves a specific parameter value as uint64_t.
     120     *
     121     * @returns IPRT status code.
     122     * @param   uParm           Index of parameter to retrieve.
     123     * @param   pu32Info        Where to store the parameter value.
     124     */
     125    int GetParmU64(uint32_t uParm, uint64_t *pu64Info) const
    90126    {
    91127        AssertPtrNullReturn(pu64Info, VERR_INVALID_PARAMETER);
    92         AssertReturn(iParm < m_cParms, VERR_INVALID_PARAMETER);
    93         AssertReturn(m_paParms[iParm].type == VBOX_HGCM_SVC_PARM_64BIT, VERR_INVALID_PARAMETER);
    94 
    95         *pu64Info = m_paParms[iParm].u.uint64;
     128        AssertReturn(uParm < m_cParms, VERR_INVALID_PARAMETER);
     129        AssertReturn(m_paParms[uParm].type == VBOX_HGCM_SVC_PARM_64BIT, VERR_INVALID_PARAMETER);
     130
     131        *pu64Info = m_paParms[uParm].u.uint64;
    96132
    97133        return VINF_SUCCESS;
    98134    }
    99135
    100     int getParmPtrInfo(uint32_t iParm, void **ppvAddr, uint32_t *pcSize) const
     136    /**
     137     * Retrieves a specific parameter value as a data address + size.
     138     *
     139     * @returns IPRT status code.
     140     * @param   uParm           Index of parameter to retrieve.
     141     * @param   ppvAddr         Where to store the data address.
     142     * @param   pcbSize         Where to store the data size (in bytes).
     143     *
     144     * @remarks Does not copy (store) the actual content of the pointer (deep copy).
     145     */
     146    int GetParmPtr(uint32_t uParm, void **ppvAddr, uint32_t *pcbSize) const
    101147    {
    102148        AssertPtrNullReturn(ppvAddr, VERR_INVALID_PARAMETER);
    103         AssertPtrNullReturn(pcSize, VERR_INVALID_PARAMETER);
    104         AssertReturn(iParm < m_cParms, VERR_INVALID_PARAMETER);
    105         AssertReturn(m_paParms[iParm].type == VBOX_HGCM_SVC_PARM_PTR, VERR_INVALID_PARAMETER);
    106 
    107         *ppvAddr = m_paParms[iParm].u.pointer.addr;
    108         *pcSize = m_paParms[iParm].u.pointer.size;
     149        AssertPtrNullReturn(pcbSize, VERR_INVALID_PARAMETER);
     150        AssertReturn(uParm < m_cParms, VERR_INVALID_PARAMETER);
     151        AssertReturn(m_paParms[uParm].type == VBOX_HGCM_SVC_PARM_PTR, VERR_INVALID_PARAMETER);
     152
     153        *ppvAddr = m_paParms[uParm].u.pointer.addr;
     154        *pcbSize = m_paParms[uParm].u.pointer.size;
    109155
    110156        return VINF_SUCCESS;
    111     }
    112 
    113     static int copyParms(PVBOXHGCMSVCPARM paParmsDst, uint32_t cParmsDst, PVBOXHGCMSVCPARM paParmsSrc, uint32_t cParmsSrc)
    114     {
    115         return copyParmsInternal(paParmsDst, cParmsDst, paParmsSrc, cParmsSrc, false /* fDeepCopy */);
    116157    }
    117158
    … …  
    154195    }
    155196
     197    /**
     198     * Copies HGCM parameters from source to destination.
     199     *
     200     * @returns IPRT status code.
     201     * @param   paParmsDst      Destination array to copy parameters to.
     202     * @param   cParmsDst       Size (in parameters) of destination array.
     203     * @param   paParmsSrc      Source array to copy parameters from.
     204     * @param   cParmsSrc       Size (in parameters) of source array.
     205     * @param   fDeepCopy       Whether to perform a deep copy of pointer parameters or not.
     206     *
     207     * @remark Static convenience function.
     208     */
    156209    static int copyParmsInternal(PVBOXHGCMSVCPARM paParmsDst, uint32_t cParmsDst,
    157210                                 PVBOXHGCMSVCPARM paParmsSrc, uint32_t cParmsSrc,
    … …  
    234287    }
    235288
    236     void cleanup()
     289    /**
     290     * Cleans up the message by free'ing all allocated parameters and resetting the rest.
     291     */
     292    void cleanup(void)
    237293    {
    238294        if (m_paParms)
    … …  
    256312};
    257313
     314/**
     315 * Class for keeping and tracking a HGCM client.
     316 */
    258317class Client
    259318{
    260319public:
     320
    261321    Client(uint32_t uClientId, VBOXHGCMCALLHANDLE hHandle = NULL,
    262322           uint32_t uMsg = 0, uint32_t cParms = 0, VBOXHGCMSVCPARM aParms[] = NULL)
    … …  
    270330public:
    271331
    272     VBOXHGCMCALLHANDLE handle(void) const { return m_hHandle; }
    273     uint32_t message(void) const { return m_uMsg; }
    274     uint32_t clientId(void) const { return m_uClientId; }
    275     uint32_t protocol(void) const { return m_uProtocol; }
     332    VBOXHGCMCALLHANDLE GetHandle(void) const { return m_hHandle; }
     333    uint32_t GetMsgType(void) const { return m_uMsg; }
     334    uint32_t GetClientID(void) const { return m_uClientId; }
     335    uint32_t GetProtocolVer(void) const { return m_uProtocol; }
    276336
    277337public:
    278338
    279     int setProtocol(uint32_t uProtocol) { m_uProtocol = uProtocol; return VINF_SUCCESS; }
     339    int SetProtocolVer(uint32_t uProtocol) { m_uProtocol = uProtocol; return VINF_SUCCESS; }
    280340
    281341public:
    … …  
    297357            return VERR_INVALID_PARAMETER;
    298358
    299         m_paParms[0].setUInt32(pMessage->message());
    300         m_paParms[1].setUInt32(pMessage->paramsCount());
     359        m_paParms[0].setUInt32(pMessage->GetType());
     360        m_paParms[1].setUInt32(pMessage->GetParamCount());
    301361
    302362        return VINF_SUCCESS;
    … …  
    305365    {
    306366        AssertPtrReturn(pMessage, VERR_INVALID_POINTER);
    307         return pMessage->getData(m_uMsg, m_cParms, m_paParms);
     367        return pMessage->GetData(m_uMsg, m_cParms, m_paParms);
    308368    }
    309369
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette