VirtualBox

Ignore:
Timestamp:
Aug 26, 2011 1:44:25 PM (13 years ago)
Author:
vboxsync
Message:

VBoxManage/GuestCtrl: Documentation, some renaming.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestCtrl.cpp

    r38525 r38551  
    814814}
    815815
     816/**
     817 * Creates a copy context structure which then can be used with various
     818 * guest control copy functions. Needs to be free'd with ctrlCopyContextFree().
     819 *
     820 * @return  IPRT status code.
     821 * @param   pGuest                  Pointer to IGuest interface to use.
     822 * @param   fVerbose                Flag indicating if we want to run in verbose mode.
     823 * @param   fHostToGuest            Flag indicating if we want to copy from host to guest
     824 *                                  or vice versa.
     825 * @param   pszUsername             Username of account to use on the guest side.
     826 * @param   pszPassword             Password of account to use.
     827 * @param   ppContext               Pointer which receives the allocated copy context.
     828 */
    816829static int ctrlCopyContextCreate(IGuest *pGuest, bool fVerbose, bool fHostToGuest,
    817830                                 const char *pszUsername, const char *pszPassword,
    … …  
    848861}
    849862
     863/**
     864 * Frees are previously allocated copy context structure.
     865 *
     866 * @param   pContext                Pointer to copy context to free.
     867 */
    850868static void ctrlCopyContextFree(PCOPYCONTEXT pContext)
    851869{
    … …  
    906924
    907925#ifdef DEBUG_andy
    908 static void tstTranslatePath()
     926static int tstTranslatePath()
    909927{
    910928    static struct
    … …  
    955973        }
    956974    }
     975
     976    return VINF_SUCCESS; /* @todo */
    957977}
    958978#endif
    959979
     980/**
     981 * Creates a directory on the destination, based on the current copy
     982 * context.
     983 *
     984 * @return  IPRT status code.
     985 * @param   pContext                Pointer to current copy control context.
     986 * @param   pszDir                  Directory to create.
     987 */
    960988static int ctrlCopyDirCreate(PCOPYCONTEXT pContext, const char *pszDir)
    961989{
    … …  
    9811009}
    9821010
     1011/**
     1012 * Checks whether a specific host/guest directory exists.
     1013 *
     1014 * @return  IPRT status code.
     1015 * @param   pContext                Pointer to current copy control context.
     1016 * @param   bGuest                  true if directory needs to be checked on the guest
     1017 *                                  or false if on the host.
     1018 * @param   pszDir                  Actual directory to check.
     1019 * @param   fExists                 Pointer which receives the result if the
     1020 *                                  given directory exists or not.
     1021 */
    9831022static int ctrlCopyDirExists(PCOPYCONTEXT pContext, bool bGuest,
    9841023                             const char *pszDir, bool *fExists)
    … …  
    10061045}
    10071046
     1047/**
     1048 * Checks whether a specific directory exists on the destination, based
     1049 * on the current copy context.
     1050 *
     1051 * @return  IPRT status code.
     1052 * @param   pContext                Pointer to current copy control context.
     1053 * @param   pszDir                  Actual directory to check.
     1054 * @param   fExists                 Pointer which receives the result if the
     1055 *                                  given directory exists or not.
     1056 */
    10081057static int ctrlCopyDirExistsOnDest(PCOPYCONTEXT pContext, const char *pszDir,
    10091058                                   bool *fExists)
    … …  
    10131062}
    10141063
     1064/**
     1065 * Checks whether a specific directory exists on the source, based
     1066 * on the current copy context.
     1067 *
     1068 * @return  IPRT status code.
     1069 * @param   pContext                Pointer to current copy control context.
     1070 * @param   pszDir                  Actual directory to check.
     1071 * @param   fExists                 Pointer which receives the result if the
     1072 *                                  given directory exists or not.
     1073 */
    10151074static int ctrlCopyDirExistsOnSource(PCOPYCONTEXT pContext, const char *pszDir,
    10161075                                     bool *fExists)
    … …  
    10201079}
    10211080
     1081/**
     1082 * Checks whether a specific host/guest file exists.
     1083 *
     1084 * @return  IPRT status code.
     1085 * @param   pContext                Pointer to current copy control context.
     1086 * @param   bGuest                  true if file needs to be checked on the guest
     1087 *                                  or false if on the host.
     1088 * @param   pszFile                 Actual file to check.
     1089 * @param   fExists                 Pointer which receives the result if the
     1090 *                                  given file exists or not.
     1091 */
    10221092static int ctrlCopyFileExists(PCOPYCONTEXT pContext, bool bOnGuest,
    10231093                              const char *pszFile, bool *fExists)
    … …  
    10441114}
    10451115
     1116/**
     1117 * Checks whether a specific file exists on the destination, based on the
     1118 * current copy context.
     1119 *
     1120 * @return  IPRT status code.
     1121 * @param   pContext                Pointer to current copy control context.
     1122 * @param   pszFile                 Actual file to check.
     1123 * @param   fExists                 Pointer which receives the result if the
     1124 *                                  given file exists or not.
     1125 */
    10461126static int ctrlCopyFileExistsOnDest(PCOPYCONTEXT pContext, const char *pszFile,
    10471127                                    bool *fExists)
    … …  
    10511131}
    10521132
     1133/**
     1134 * Checks whether a specific file exists on the source, based on the
     1135 * current copy context.
     1136 *
     1137 * @return  IPRT status code.
     1138 * @param   pContext                Pointer to current copy control context.
     1139 * @param   pszFile                 Actual file to check.
     1140 * @param   fExists                 Pointer which receives the result if the
     1141 *                                  given file exists or not.
     1142 */
    10531143static int ctrlCopyFileExistsOnSource(PCOPYCONTEXT pContext, const char *pszFile,
    10541144                                      bool *fExists)
    … …  
    10581148}
    10591149
    1060 static int ctrlCopyFileToTarget(PCOPYCONTEXT pContext, const char *pszFileSource,
    1061                                 const char *pszFileDest, uint32_t fFlags)
     1150/**
     1151 * Copies a source file to the destination.
     1152 *
     1153 * @return  IPRT status code.
     1154 * @param   pContext                Pointer to current copy control context.
     1155 * @param   pszFileSource           Source file to copy to the destination.
     1156 * @param   pszFileDest             Name of copied file on the destination.
     1157 * @param   fFlags                  Copy flags. No supported at the moment and needs
     1158 *                                  to be set to 0.
     1159 */
     1160static int ctrlCopyFileToDest(PCOPYCONTEXT pContext, const char *pszFileSource,
     1161                              const char *pszFileDest, uint32_t fFlags)
    10621162{
    10631163    AssertPtrReturn(pContext, VERR_INVALID_POINTER);
    10641164    AssertPtrReturn(pszFileSource, VERR_INVALID_POINTER);
    10651165    AssertPtrReturn(pszFileDest, VERR_INVALID_POINTER);
     1166    AssertReturn(!fFlags, VERR_INVALID_POINTER); /* No flags supported yet. */
    10661167
    10671168    if (pContext->fVerbose)
    … …  
    10981199}
    10991200
     1201/**
     1202 * Copys a directory (tree) from host to the guest.
     1203 *
     1204 * @return  IPRT status code.
     1205 * @param   pContext                Pointer to current copy control context.
     1206 * @param   pszSource               Source directory on the host to copy to the guest.
     1207 * @param   pszFilter               DOS-style wildcard filter (?, *).  Optional.
     1208 * @param   pszDest                 Destination directory on the guest.
     1209 * @param   fFlags                  Copy flags, such as recursive copying.
     1210 * @param   pszSubDir               Current sub directory to handle. Needs to NULL and only
     1211 *                                  is needed for recursion.
     1212 */
    11001213static int ctrlCopyDirToGuest(PCOPYCONTEXT pContext,
    11011214                              const char *pszSource, const char *pszFilter,
    … …  
    12161329                                if (RT_SUCCESS(rc))
    12171330                                {
    1218                                     rc = ctrlCopyFileToTarget(pContext, pszFileSource,
    1219                                                               pszFileDest, 0 /* Flags? */);
     1331                                    rc = ctrlCopyFileToDest(pContext, pszFileSource,
     1332                                                            pszFileDest, 0 /* Flags */);
    12201333                                    RTStrFree(pszFileDest);
    12211334                                }
    … …  
    12391352}
    12401353
     1354/**
     1355 * Copys a directory (tree) from guest to the host.
     1356 *
     1357 * @return  IPRT status code.
     1358 * @param   pContext                Pointer to current copy control context.
     1359 * @param   pszSource               Source directory on the guest to copy to the host.
     1360 * @param   pszFilter               DOS-style wildcard filter (?, *).  Optional.
     1361 * @param   pszDest                 Destination directory on the host.
     1362 * @param   fFlags                  Copy flags, such as recursive copying.
     1363 * @param   pszSubDir               Current sub directory to handle. Needs to NULL and only
     1364 *                                  is needed for recursion.
     1365 */
    12411366static int ctrlCopyDirToHost(PCOPYCONTEXT pContext,
    12421367                             const char *pszSource, const char *pszFilter,
    … …  
    13541479                                if (RT_SUCCESS(rc))
    13551480                                {
    1356                                     rc = ctrlCopyFileToTarget(pContext, pszFileSource,
    1357                                                               pszFileDest, 0 /* Flags? */);
     1481                                    rc = ctrlCopyFileToDest(pContext, pszFileSource,
     1482                                                            pszFileDest, 0 /* Flags */);
    13581483                                    RTStrFree(pszFileDest);
    13591484                                }
    … …  
    13951520}
    13961521
    1397 static int ctrlCopyDirToTarget(PCOPYCONTEXT pContext,
    1398                                const char *pszSource, const char *pszFilter,
    1399                                const char *pszDest, uint32_t fFlags,
    1400                                const char *pszSubDir /* For recursion */)
     1522/**
     1523 * Copys a directory (tree) to the destination, based on the current copy
     1524 * context.
     1525 *
     1526 * @return  IPRT status code.
     1527 * @param   pContext                Pointer to current copy control context.
     1528 * @param   pszSource               Source directory to copy to the destination.
     1529 * @param   pszFilter               DOS-style wildcard filter (?, *).  Optional.
     1530 * @param   pszDest                 Destination directory where to copy in the source
     1531 *                                  source directory.
     1532 * @param   fFlags                  Copy flags, such as recursive copying.
     1533 */
     1534static int ctrlCopyDirToDest(PCOPYCONTEXT pContext,
     1535                             const char *pszSource, const char *pszFilter,
     1536                             const char *pszDest, uint32_t fFlags)
    14011537{
    14021538    if (pContext->fHostToGuest)
    14031539        return ctrlCopyDirToGuest(pContext, pszSource, pszFilter,
    1404                                   pszDest, fFlags, pszSubDir);
     1540                                  pszDest, fFlags, NULL /* Sub directory, only for recursion. */);
    14051541    return ctrlCopyDirToHost(pContext, pszSource, pszFilter,
    1406                              pszDest, fFlags, pszSubDir);
    1407 }
    1408 
     1542                             pszDest, fFlags, NULL /* Sub directory, only for recursion. */);
     1543}
     1544
     1545/**
     1546 * Creates a source root by stripping file names or filters of the specified source.
     1547 *
     1548 * @return  IPRT status code.
     1549 * @param   pszSource               Source to create source root for.
     1550 * @param   ppszSourceRoot          Pointer that receives the allocated source root. Needs
     1551 *                                  to be free'd with ctrlCopyFreeSourceRoot().
     1552 */
    14091553static int ctrlCopyCreateSourceRoot(const char *pszSource, char **ppszSourceRoot)
    14101554{
    … …  
    14391583}
    14401584
     1585/**
     1586 * Frees a previously allocated source root.
     1587 *
     1588 * @return  IPRT status code.
     1589 * @param   pszSourceRoot           Source root to free.
     1590 */
    14411591static void ctrlCopyFreeSourceRoot(char *pszSourceRoot)
    14421592{
    … …  
    14631613     * does in here.
    14641614     */
    1465 
    1466 #ifdef DEBUG_andy
    1467     tstTranslatePath();
    1468     return VINF_SUCCESS;
    1469 #endif
    1470 
    14711615    static const RTGETOPTDEF s_aOptions[] =
    14721616    {
    … …  
    16681812                    if (RT_SUCCESS(vrc))
    16691813                    {
    1670                         vrc = ctrlCopyFileToTarget(pContext, pszSource,
    1671                                                    pszDestFile, fFlags);
     1814                        vrc = ctrlCopyFileToDest(pContext, pszSource,
     1815                                                 pszDestFile, 0 /* Flags */);
    16721816                        RTStrFree(pszDestFile);
    16731817                    }
    … …  
    16811825                {
    16821826                    /* Directory (with filter?). */
    1683                     vrc = ctrlCopyDirToTarget(pContext, pszSource, pszFilter,
    1684                                               Utf8Dest.c_str(), fFlags, NULL /* Subdir */);
     1827                    vrc = ctrlCopyDirToDest(pContext, pszSource, pszFilter,
     1828                                            Utf8Dest.c_str(), fFlags);
    16851829                }
    16861830            }
    … …  
    20572201    AssertPtrReturn(pArg, VERR_INVALID_PARAMETER);
    20582202
     2203#ifdef DEBUG_andy
     2204    if (RT_FAILURE(tstTranslatePath()))
     2205        return RTEXITCODE_FAILURE;
     2206#endif
     2207
    20592208    HandlerArg arg = *pArg;
    20602209    arg.argc = pArg->argc - 2; /* Skip VM name and sub command. */
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