VirtualBox

Changeset 99405 in vbox


Ignore:
Timestamp:
Apr 14, 2023 3:43:12 PM (2 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
156855
Message:

Shared Clipboard/Transfers: Added ShClTransferCreateEx() and some defines for transfer defaults, more documentation for struct typedefs. bugref:9437

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/GuestHost/SharedClipboard-transfers.h

    r98103 r99405  
    5959
    6060struct SHCLTRANSFER;
    61 /** Pointer to a single shared clipboard transfer  */
     61/** Pointer to a single shared clipboard transfer. */
    6262typedef struct SHCLTRANSFER *PSHCLTRANSFER;
    6363
    … …  
    6767 */
    6868
     69/** No Shared Clipboard listing feature flags defined. */
     70#define SHCL_TRANSFER_LIST_FEATURE_F_NONE            UINT32_C(0)
     71/** Shared Clipboard feature flags valid mask. */
     72#define SHCL_TRANSFER_LIST_FEATURE_F_VALID_MASK      0x0
     73
    6974/** Defines the maximum length (in chars) a Shared Clipboard transfer path can have. */
    70 #define SHCL_TRANSFER_PATH_MAX          RTPATH_MAX
     75#define SHCL_TRANSFER_PATH_MAX                  RTPATH_MAX
     76/** Defines the default maximum transfer chunk size (in bytes) of a Shared Clipboard transfer. */
     77#define SHCL_TRANSFER_DEFAULT_MAX_CHUNK_SIZE    _64K
     78/** Defines the default maximum list handles a Shared Clipboard transfer can have. */
     79#define SHCL_TRANSFER_DEFAULT_MAX_LIST_HANDLES  _4K
     80/** Defines the default maximum object handles a Shared Clipboard transfer can have. */
     81#define SHCL_TRANSFER_DEFAULT_MAX_OBJ_HANDLES   _4K
    7182
    7283/**
    … …  
    338349     */
    339350    SHCLFSOBJINFO    ObjInfo;
    340 } SHCLOBJOPENCREATEPARMS, *PSHCLOBJOPENCREATEPARMS;
     351} SHCLOBJOPENCREATEPARMS;
     352/** Pointer to Shared Clipboard object open/create parameters. */
     353typedef SHCLOBJOPENCREATEPARMS *PSHCLOBJOPENCREATEPARMS;
    341354
    342355/**
    … …  
    345358typedef struct _SHCLREPLY
    346359{
    347     /** Message type of type VBOX_SHCL_REPLYMSGTYPE_XXX. */
     360    /** Message type (of type VBOX_SHCL_REPLYMSGTYPE_TRANSFER_XXX). */
    348361    uint32_t uType;
    349362    /** IPRT result of overall operation. Note: int vs. uint32! */
    … …  
    351364    union
    352365    {
     366        /** For VBOX_SHCL_REPLYMSGTYPE_TRANSFER_STATUS. */
    353367        struct
    354368        {
    355369            SHCLTRANSFERSTATUS uStatus;
    356370        } TransferStatus;
     371        /** For VBOX_SHCL_REPLYMSGTYPE_LIST_OPEN. */
    357372        struct
    358373        {
    359374            SHCLLISTHANDLE uHandle;
    360375        } ListOpen;
     376        /** For VBOX_SHCL_REPLYMSGTYPE_LIST_CLOSE. */
    361377        struct
    362378        {
    363379            SHCLLISTHANDLE uHandle;
    364380        } ListClose;
     381        /** For VBOX_SHCL_REPLYMSGTYPE_OBJ_OPEN. */
    365382        struct
    366383        {
    367384            SHCLOBJHANDLE uHandle;
    368385        } ObjOpen;
     386        /** For VBOX_SHCL_REPLYMSGTYPE_OBJ_CLOSE. */
    369387        struct
    370388        {
    … …  
    376394    /** Payload size (in bytes). */
    377395    uint32_t cbPayload;
    378 } SHCLREPLY, *PSHCLREPLY;
     396} SHCLREPLY;
     397/** Pointer to a Shared Clipboard reply. */
     398typedef SHCLREPLY *PSHCLREPLY;
    379399
    380400struct _SHCLLISTENTRY;
    … …  
    395415    /** Number of root list entries. */
    396416    uint32_t                cRoots;
    397 } SHCLROOTLISTHDR, *PSHCLROOTLISTHDR;
     417} SHCLROOTLISTHDR;
     418/** Pointer to a Shared Clipboard root list header. */
     419typedef SHCLROOTLISTHDR *PSHCLROOTLISTHDR;
    398420
    399421/**
    … …  
    406428    /** Root list entries. */
    407429    SHCLROOTLISTENTRY *paEntries;
    408 } SHCLROOTLIST, *PSHCLROOTLIST;
    409 
    410 /**
    411  * Structure for maintaining Shared Clipboard list open paramters.
     430} SHCLROOTLIST;
     431/** Pointer to a Shared Clipboard root list. */
     432typedef SHCLROOTLIST *PSHCLROOTLIST;
     433
     434/**
     435 * Structure for maintaining Shared Clipboard list open parameters.
    412436 */
    413437typedef struct _SHCLLISTOPENPARMS
    … …  
    423447    /** Listing path (absolute). If empty or NULL the listing's root path will be opened. */
    424448    char    *pszPath;
    425 } SHCLLISTOPENPARMS, *PSHCLLISTOPENPARMS;
     449} SHCLLISTOPENPARMS;
     450/** Pointer to Shared Clipboard list open parameters. */
     451typedef SHCLLISTOPENPARMS *PSHCLLISTOPENPARMS;
    426452
    427453/**
    … …  
    430456typedef struct _SHCLLISTHDR
    431457{
    432     /** Feature flag(s). Not being used atm. */
     458    /** Feature flag(s) of type SHCL_TRANSFER_LIST_FEATURE_F_XXX. */
    433459    uint32_t fFeatures;
    434460    /** Total objects returned. */
    … …  
    436462    /** Total size (in bytes) returned. */
    437463    uint64_t cbTotalSize;
    438 } SHCLLISTHDR, *PSHCLLISTHDR;
     464} SHCLLISTHDR;
     465/** Pointer to a Shared Clipboard list header. */
     466typedef SHCLLISTHDR *PSHCLLISTHDR;
    439467
    440468/**
    … …  
    453481    /** Data of the actual list entry. */
    454482    void    *pvInfo;
    455 } SHCLLISTENTRY, *PSHCLLISTENTRY;
     483} SHCLLISTENTRY;
     484/** Pointer to a Shared Clipboard list entry. */
     485typedef SHCLLISTENTRY *PSHCLLISTENTRY;
    456486
    457487/** Maximum length (in UTF-8 characters) of a list entry name. */
    … …  
    459489
    460490/**
    461  * Structure for maintaining a Shared Clipboard list.
     491 * Structure for maintaining a generic Shared Clipboard list.
    462492 */
    463493typedef struct _SHCLLIST
    … …  
    467497    /** List entries. */
    468498    SHCLROOTLISTENTRY *paEntries;
    469 } SHCLLIST, *PSHCLLIST;
     499} SHCLLIST;
     500/** Pointer to a Shared Clipboard transfer transfer list. */
     501typedef SHCLLIST *PSHCLLIST;
    470502
    471503/**
    … …  
    480512    /** Size (in bytes) of data chunk. */
    481513    uint32_t  cbData;
    482 } SHCLOBJDATACHUNK, *PSHCLOBJDATACHUNK;
     514} SHCLOBJDATACHUNK;
     515/** Pointer to a Shared Clipboard transfer object data chunk. */
     516typedef SHCLOBJDATACHUNK *PSHCLOBJDATACHUNK;
    483517
    484518/**
    … …  
    487521typedef struct _SHCLCLIENTTRANSFEROBJCTX
    488522{
     523    /** Pointer to the actual transfer object of this context. */
    489524    SHCLTRANSFER *pTransfer;
     525    /** Object handle of this transfer context. */
    490526    SHCLOBJHANDLE uHandle;
    491 } SHCLCLIENTTRANSFEROBJCTX, *PSHCLCLIENTTRANSFEROBJCTX;
     527} SHCLCLIENTTRANSFEROBJCTX;
     528/** Pointer to a Shared Clipboard transfer object context. */
     529typedef SHCLCLIENTTRANSFEROBJCTX *PSHCLCLIENTTRANSFEROBJCTX;
    492530
    493531typedef struct _SHCLTRANSFEROBJSTATE
    … …  
    495533    /** How many bytes were processed (read / write) so far. */
    496534    uint64_t cbProcessed;
    497 } SHCLTRANSFEROBJSTATE, *PSHCLTRANSFEROBJSTATE;
    498 
     535} SHCLTRANSFEROBJSTATE;
     536/** Pointer to a Shared Clipboard transfer object state. */
     537typedef SHCLTRANSFEROBJSTATE *PSHCLTRANSFEROBJSTATE;
     538
     539/**
     540 * Structure for a Shared Clipboard transfer object.
     541 */
    499542typedef struct _SHCLTRANSFEROBJ
    500543{
     544    /** Handle of the object. */
    501545    SHCLOBJHANDLE        uHandle;
     546    /** Absolute (local) path of the object. Source-style path. */
    502547    char                *pszPathAbs;
     548    /** Object information. */
    503549    SHCLFSOBJINFO        objInfo;
     550    /** Object type. */
    504551    SHCLSOURCE           enmSource;
     552    /** Current state. */
    505553    SHCLTRANSFEROBJSTATE State;
    506 } SHCLTRANSFEROBJ, *PSHCLTRANSFEROBJ;
     554} SHCLTRANSFEROBJ;
     555/** Pointer to a Shared Clipboard transfer object. */
     556typedef SHCLTRANSFEROBJ *PSHCLTRANSFEROBJ;
    507557
    508558/**
    … …  
    525575/**
    526576 * Structure for keeping transfer list handle information.
     577 *
    527578 * This is using to map own (local) handles to the underlying file system.
    528579 */
    … …  
    549600        } Local;
    550601    } u;
    551 } SHCLLISTHANDLEINFO, *PSHCLLISTHANDLEINFO;
     602} SHCLLISTHANDLEINFO;
     603/** Pointer to a Shared Clipboard transfer list handle info. */
     604typedef SHCLLISTHANDLEINFO *PSHCLLISTHANDLEINFO;
    552605
    553606/**
    … …  
    565618    /** Absolute local path of the object. */
    566619    char          *pszPathLocalAbs;
     620    /** Data union, based on \a enmType. */
    567621    union
    568622    {
    569         /** Local data, based on enmType. */
     623        /** Local data. */
    570624        struct
    571625        {
    … …  
    577631        } Local;
    578632    } u;
    579 } SHCLOBJHANDLEINFO, *PSHCLOBJHANDLEINFO;
    580 
    581 /**
    582  * Structure for keeping a single root list entry.
     633} SHCLOBJHANDLEINFO;
     634/** Pointer to a Shared Clipboard transfer object handle. */
     635typedef SHCLOBJHANDLEINFO *PSHCLOBJHANDLEINFO;
     636
     637/**
     638 * Structure for keeping a single transfer root list entry.
    583639 */
    584640typedef struct _SHCLLISTROOT
    … …  
    588644    /** Absolute path of entry. */
    589645    char               *pszPathAbs;
    590 } SHCLLISTROOT, *PSHCLLISTROOT;
     646} SHCLLISTROOT;
     647/** Pointer to a Shared Clipboard transfer root list entry. */
     648typedef SHCLLISTROOT *PSHCLLISTROOT;
    591649
    592650/**
    … …  
    604662    /** The transfer's source, seen from the perspective who created the transfer. */
    605663    SHCLSOURCE         enmSource;
    606 } SHCLTRANSFERSTATE, *PSHCLTRANSFERSTATE;
     664} SHCLTRANSFERSTATE;
     665/** Pointer to a Shared Clipboard transfer state. */
     666typedef SHCLTRANSFERSTATE *PSHCLTRANSFERSTATE;
    607667
    608668/**
    609669 * Structure maintaining clipboard transfer provider context data.
    610  * This is handed in to the provider interface implementations.
     670 *
     671 * This is handed-in to the provider interface implementations.
    611672 */
    612673typedef struct _SHCLTXPROVIDERCTX
    … …  
    618679    /** Size (in bytes) of data at user pointer. */
    619680    size_t        cbUser;
    620 } SHCLTXPROVIDERCTX, *PSHCLTXPROVIDERCTX;
     681} SHCLTXPROVIDERCTX;
     682/** Pointer to Shared Clipboard transfer provider context data. */
     683typedef SHCLTXPROVIDERCTX *PSHCLTXPROVIDERCTX;
    621684
    622685struct SHCLTRANSFERCTX;
    … …  
    644707    DECLCALLBACKMEMBER(int, pfnObjWrite,(PSHCLTXPROVIDERCTX pCtx, SHCLOBJHANDLE hObj, void *pvData, uint32_t cbData,
    645708                                         uint32_t fFlags, uint32_t *pcbWritten));
    646 } SHCLTXPROVIDERIFACE, *PSHCLTXPROVIDERIFACE;
     709} SHCLTXPROVIDERIFACE;
     710/** Pointer to a Shared Clipboard transfer provider interface table. */
     711typedef SHCLTXPROVIDERIFACE *PSHCLTXPROVIDERIFACE;
    647712
    648713/**
    … …  
    659724    /** Size (in bytes) of data at user pointer. */
    660725    size_t               cbUser;
    661 } SHCLTXPROVIDERCREATIONCTX, *PSHCLTXPROVIDERCREATIONCTX;
     726} SHCLTXPROVIDERCREATIONCTX;
     727/** Pointer to a Shared Clipboard transfer provider creation context. */
     728typedef SHCLTXPROVIDERCREATIONCTX *PSHCLTXPROVIDERCREATIONCTX;
    662729
    663730/**
    … …  
    672739    /** Size (in bytes) of data at user pointer. */
    673740    size_t        cbUser;
    674 } SHCLTRANSFERCALLBACKCTX, *PSHCLTRANSFERCALLBACKCTX;
     741} SHCLTRANSFERCALLBACKCTX;
     742/** Pointer to a Shared Clipboard transfer callback context. */
     743typedef SHCLTRANSFERCALLBACKCTX *PSHCLTRANSFERCALLBACKCTX;
    675744
    676745/**
    … …  
    727796    /** Size (in bytes) of data pointer at \a pvUser. */
    728797    size_t cbUser;
    729 } SHCLTRANSFERCALLBACKTABLE, *PSHCLTRANSFERCALLBACKTABLE;
     798} SHCLTRANSFERCALLBACKTABLE;
     799/** Pointer to a Shared Clipboard transfer callback table. */
     800typedef SHCLTRANSFERCALLBACKTABLE *PSHCLTRANSFERCALLBACKTABLE;
    730801
    731802/**
    … …  
    743814    /** Thread cancelled flag / indicator. */
    744815    volatile bool               fCancelled;
    745 } SHCLTRANSFERTHREAD, *PSHCLTRANSFERTHREAD;
     816} SHCLTRANSFERTHREAD;
     817/** Pointer to a Shared Clipboard transfer thread. */
     818typedef SHCLTRANSFERTHREAD *PSHCLTRANSFERTHREAD;
    746819
    747820/**
    … …  
    800873    /** Critical section for serializing access. */
    801874    RTCRITSECT                CritSect;
    802 } SHCLTRANSFER, *PSHCLTRANSFER;
     875} SHCLTRANSFER;
     876/** Pointer to a Shared Clipboard transfer. */
     877typedef SHCLTRANSFER *PSHCLTRANSFER;
    803878
    804879/**
    … …  
    813888    /** Reporting flags. Currently unused and must be 0. */
    814889    uint32_t              fFlags;
    815 } SHCLTRANSFERREPORT, *PSHCLTRANSFERREPORT;
     890} SHCLTRANSFERREPORT;
     891/** Pointer to Shared Clipboard transfer status. */
     892typedef SHCLTRANSFERREPORT *PSHCLTRANSFERREPORT;
    816893
    817894#ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
    … …  
    831908    RTHTTPSERVERRESP    Resp;
    832909} SHCLHTTPSERVER;
     910/** Pointer to Shared Clipboard HTTP server. */
    833911typedef SHCLHTTPSERVER *PSHCLHTTPSERVER;
    834912
    … …  
    838916    SHCLHTTPSERVER      HttpServer;
    839917} SHCLHTTPCONTEXT;
     918/** Pointer to Shared Clipboard HTTP transfer context. */
    840919typedef SHCLHTTPCONTEXT *PSHCLHTTPCONTEXT;
    841920
    … …  
    885964void ShClTransferObjDataChunkFree(PSHCLOBJDATACHUNK pDataChunk);
    886965
     966int ShClTransferCreateEx(uint32_t cbMaxChunkSize, uint32_t cMaxListHandles, uint32_t cMaxObjHandles, PSHCLTRANSFER *ppTransfer);
    887967int ShClTransferCreate(PSHCLTRANSFER *ppTransfer);
    888968int ShClTransferInit(PSHCLTRANSFER pTransfer, SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource);

  • trunk/src/VBox/GuestHost/SharedClipboard/clipboard-transfers.cpp

    r99403 r99405  
    11651165
    11661166/**
    1167  * Creates a clipboard transfer.
    1168  *
    1169  * @returns VBox status code.
     1167 * Creates a clipboard transfer, extended version.
     1168 *
     1169 * @returns VBox status code.
     1170 * @param   cbMaxChunkSize      Maximum transfer chunk size (in bytes) to use.
     1171 * @param   cMaxListHandles     Maximum list entries the transfer can have.
     1172 * @param   cMaxObjHandles      Maximum transfer objects the transfer can have.
    11701173 * @param   ppTransfer          Where to return the created clipboard transfer struct.
    11711174 *                              Must be destroyed by ShClTransferDestroy().
    11721175 */
    1173 int ShClTransferCreate(PSHCLTRANSFER *ppTransfer)
    1174 {
     1176int ShClTransferCreateEx(uint32_t cbMaxChunkSize, uint32_t cMaxListHandles, uint32_t cMaxObjHandles,
     1177                         PSHCLTRANSFER *ppTransfer)
     1178{
     1179
     1180
    11751181    AssertPtrReturn(ppTransfer, VERR_INVALID_POINTER);
    11761182
    … …  
    11971203    pTransfer->uTimeoutMs     = RT_MS_30SEC;
    11981204#endif
    1199     pTransfer->cbMaxChunkSize  = _64K; /** @todo Make this configurable. */
    1200     pTransfer->cMaxListHandles = _4K;  /** @todo Ditto. */
    1201     pTransfer->cMaxObjHandles  = _4K;  /** @todo Ditto. */
     1205    pTransfer->cbMaxChunkSize  = cbMaxChunkSize;
     1206    pTransfer->cMaxListHandles = cMaxListHandles;
     1207    pTransfer->cMaxObjHandles  = cMaxObjHandles;
    12021208
    12031209    pTransfer->pvUser = NULL;
    … …  
    12261232    LogFlowFuncLeaveRC(rc);
    12271233    return rc;
     1234}
     1235
     1236/**
     1237 * Creates a clipboard transfer with default settings.
     1238 *
     1239 * @returns VBox status code.
     1240 * @param   ppTransfer          Where to return the created clipboard transfer struct.
     1241 *                              Must be destroyed by ShClTransferDestroy().
     1242 */
     1243int ShClTransferCreate(PSHCLTRANSFER *ppTransfer)
     1244{
     1245    return ShClTransferCreateEx(SHCL_TRANSFER_DEFAULT_MAX_CHUNK_SIZE,
     1246                                SHCL_TRANSFER_DEFAULT_MAX_LIST_HANDLES,
     1247                                SHCL_TRANSFER_DEFAULT_MAX_OBJ_HANDLES,
     1248                                ppTransfer);
    12281249}
    12291250
Note: See TracChangeset for help on using the changeset viewer.

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