VirtualBox

Changeset 62793 in vbox for trunk/src/VBox


Ignore:
Timestamp:
Aug 1, 2016 7:30:17 AM (8 years ago)
Author:
vboxsync
Message:

VBoxClipbaord-win.cpp: We document using doxygen! Don't put the format string miles away from the actual use.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/HostServices/SharedClipboard/VBoxClipboard-win.cpp

    r62792 r62793  
    10201020}
    10211021
    1022 /*
    1023 @StartHtml - pos before <html>
    1024 @EndHtml - whole size of text excluding ending zero char
    1025 @StartFragment - pos after <!--StartFragment-->
    1026 @EndFragment - pos before <!--EndFragment-->
    1027 @note: all values includes CR\LF inserted into text
    1028 Calculations:
    1029 Header length = format Length + (3*6('digits')) - 2('%s') = format length + 16 (control value - 183)
    1030 EndHtml  = Header length + fragment length
    1031 StartHtml = 105(constant)
    1032 StartFragment = 143(constant)
    1033 EndFragment  = Header length + fragment length - 40(ending length)
    1034 */
    1035 const char pcszFormatSample[] =
    1036     "Version:1.0\r\n"
    1037     "StartHTML:000000101\r\n"
    1038     "EndHTML:%09d\r\n" // END HTML = Header length + fragment lengh
    1039 "StartFragment:000000137\r\n"
    1040 "EndFragment:%09d\r\n"
    1041 "<html>\r\n"
    1042 "<body>\r\n"
    1043 "<!--StartFragment-->%s<!--EndFragment-->\r\n"
    1044 "</body>\r\n"
    1045 "</html>\r\n";
    1046 
    1047 /*
    1048 * Extracts field value from CF_HTML struct
    1049 * @src - source in CF_HTML format
    1050 * @option - name of CF_HTML field
    1051 * @value - extracted value of CF_HTML field
    1052 * returns RC result code
    1053 */
     1022
     1023/**
     1024 * Extracts field value from CF_HTML struct
     1025 *
     1026 * @returns VBox status code
     1027 * @param   pcszSrc     source in CF_HTML format
     1028 * @param   pcszOption  Name of CF_HTML field
     1029 * @param   pcValue     Where to return extracted value of CF_HTML field
     1030 */
    10541031int GetHeaderValue(const char *pcszSrc, const char *pcszOption, size_t *pcValue)
    10551032{
    … …  
    10791056}
    10801057
    1081 /*
     1058
     1059/**
    10821060 * Check that the source string contains CF_HTML struct
    1083  * returns true if the @source string is in CF_HTML format
     1061 *
     1062 * @returns @c true if the @source string is in CF_HTML format
    10841063 */
    10851064bool IsWindowsHTML(const char *pcszSource)
    … …  
    10921071/*
    10931072 * Converts clipboard data from CF_HTML format to mimie clipboard format
     1073 *
    10941074 * Returns allocated buffer that contains html converted to text/html mime type
    1095  * return result code
    1096  * parameters - output buffer and size of output buffer
    1097  * It allocates the buffer needed for storing converted fragment
    1098  * Allocated buffer should be destroyed by RTMemFree after usage
     1075 *
     1076 * @returns VBox status code.
     1077 * @param   pcszSource  The input.
     1078 * @param   cch         The length of the input.
     1079 * @param   ppszOutput  Where to return the result.  Free using RTMemFree.
     1080 * @param   pcch        Where to the return length of the result (bytes/chars).
    10991081 */
    11001082int ConvertCFHtmlToMime(const char *pcszSource, const uint32_t cch, char **ppszOutput, size_t *pcch)
    11011083{
    1102     char* result = NULL;
     1084    char *result = NULL;
    11031085
    11041086    Assert(pcszSource);
    … …  
    11461128    }
    11471129
    1148 return VINF_SUCCESS;
     1130    return VINF_SUCCESS;
    11491131}
    11501132
    … …  
    11521134
    11531135/*
    1154 * Converts source Utf16 mime html clipboard data to Utf8 CF_HTML format
    1155 * It allocates
    1156 * Calculations:
    1157 * Header length = format Length + (2*(10 - 5('%010d'))('digits')) - 2('%s') = format length + 8
    1158 * EndHtml  = Header length + fragment length
    1159 * StartHtml = 105(constant)
    1160 * StartFragment = 141(constant) may vary if the header html content will be extended
    1161 * EndFragment  = Header length + fragment length - 38(ending length)
    1162 * @source: source buffer that contains utf-16 string in mime html format
    1163 * @cb: size of source buffer in bytes
    1164 * @output: allocated output buffer to put converted Utf8 CF_HTML clipboard data. This function allocates memory for this.
    1165 * @pcch: size of allocated result buffer in bytes
    1166 * @note: output buffer should be free using RTMemFree()
    1167 * @note: Everything inside of fragment can be UTF8. Windows allows it. Everything in header should be Latin1.
    1168 */
    1169 int ConvertMimeToCFHTML(const char *pcszSource, size_t cb, char **pszOutput, size_t *pcch)
     1136 * Converts source Utf16 mime html clipboard data to Utf8 CF_HTML format.
     1137 *
     1138 * It allocates
     1139 *
     1140 * Calculations:
     1141 *   Header length = format Length + (2*(10 - 5('%010d'))('digits')) - 2('%s') = format length + 8
     1142 *   EndHtml       = Header length + fragment length
     1143 *   StartHtml     = 105(constant)
     1144 *   StartFragment = 141(constant) may vary if the header html content will be extended
     1145 *   EndFragment   = Header length + fragment length - 38(ending length)
     1146 *
     1147 * @param   pcszSource  Source buffer that contains utf-16 string in mime html format
     1148 * @param   cb          Size of source buffer in bytes
     1149 * @param   ppszOutput  Where to return the allocated output buffer to put converted UTF-8
     1150 *                      CF_HTML clipboard data.  This function allocates memory for this.
     1151 * @param   pcch        Where to return the Size of allocated result buffer in bytes/chars.
     1152 *
     1153 * @note    output buffer should be free using RTMemFree()
     1154 * @note    Everything inside of fragment can be UTF8. Windows allows it. Everything in header should be Latin1.
     1155 */
     1156int ConvertMimeToCFHTML(const char *pcszSource, size_t cb, char **ppszOutput, size_t *pcch)
    11701157{
    11711158    Assert(pszOutput);
    … …  
    11761163    size_t cFragmentLength = 0;
    11771164
    1178     char* pszBuf = (char*)pcszSource;
     1165    char *pszBuf = (char *)pcszSource;
    11791166
    11801167    /* construct CF_HTML formatted string */
    … …  
    11871174    }
    11881175
    1189     /* caluclate parameters of CF_HTML header */
    1190     size_t cHeaderLength = (sizeof(pcszFormatSample) - 1) + 8;
     1176    /*
     1177    @StartHtml - pos before <html>
     1178    @EndHtml - whole size of text excluding ending zero char
     1179    @StartFragment - pos after <!--StartFragment-->
     1180    @EndFragment - pos before <!--EndFragment-->
     1181    @note: all values includes CR\LF inserted into text
     1182    Calculations:
     1183    Header length = format Length + (3*6('digits')) - 2('%s') = format length + 16 (control value - 183)
     1184    EndHtml  = Header length + fragment length
     1185    StartHtml = 105(constant)
     1186    StartFragment = 143(constant)
     1187    EndFragment  = Header length + fragment length - 40(ending length)
     1188    */
     1189    static const char s_szFormatSample[] =
     1190        "Version:1.0\r\n"
     1191        "StartHTML:000000101\r\n"
     1192        "EndHTML:%09d\r\n" // END HTML = Header length + fragment lengh
     1193        "StartFragment:000000137\r\n"
     1194        "EndFragment:%09d\r\n"
     1195        "<html>\r\n"
     1196        "<body>\r\n"
     1197        "<!--StartFragment-->%s<!--EndFragment-->\r\n"
     1198        "</body>\r\n"
     1199        "</html>\r\n";
     1200
     1201    /* calculate parameters of CF_HTML header */
     1202    size_t cHeaderLength = (sizeof(s_szFormatSample) - 1) + 8;
    11911203    size_t cEndHtml = cHeaderLength + cFragmentLength;
    11921204    size_t cEndFragment = cHeaderLength + cFragmentLength - 38;
    … …  
    11991211
    12001212    /* format result CF_HTML string */
    1201     rc = RTStrPrintf(pszResult, cEndHtml + 1, pcszFormatSample, cEndHtml, cEndFragment, pszBuf);
     1213    rc = RTStrPrintf(pszResult, cEndHtml + 1, s_szFormatSample, cEndHtml, cEndFragment, pszBuf);
    12021214    if (rc == -1)
    12031215    {
    … …  
    12231235#endif
    12241236
    1225     *pszOutput = pszResult;
     1237    *ppszOutput = pszResult;
    12261238    *pcch = rc + 1;
    12271239
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