Merge to Master: Cover fpdftext.h API with embeddertests.

fpdfsdk/include/fpdftext.h

 // Copyright 2014 PDFium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
  
 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
 
 #ifndef _FPDFTEXT_H_
 #define _FPDFTEXT_H_
 
 #include "fpdfview.h"
 
 // Exported Functions
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // Function: FPDFText_LoadPage
 //                      Prepare information about all characters in a page.
-// Parameters: 
-//                      page    -       Handle to the page. Returned by FPDF_LoadPage function (in FPDFVIEW module).    
+// Parameters:
+//                      page    -       Handle to the page. Returned by FPDF_LoadPage function (in FPDFVIEW module).
 // Return value:
 //                      A handle to the text page information structure.
 //                      NULL if something goes wrong.
 // Comments:
 //                      Application must call FPDFText_ClosePage to release the text page information.
-//                      If you don't purchase Text Module , this function will return NULL.
-//      
+//
 DLLEXPORT FPDF_TEXTPAGE STDCALL FPDFText_LoadPage(FPDF_PAGE page);
 
 // Function: FPDFText_ClosePage
 //                      Release all resources allocated for a text page information structure.
-// Parameters: 
+// Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 // Return Value:
 //                      None.
 //
 DLLEXPORT void STDCALL FPDFText_ClosePage(FPDF_TEXTPAGE text_page);
-        
+
 // Function: FPDFText_CountChars
 //                      Get number of characters in a page.
-// Parameters: 
+// Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 // Return value:
-//                      Number of characters in the page. Return -1 for error. 
+//                      Number of characters in the page. Return -1 for error.
 //                      Generated characters, like additional space characters, new line characters, are also counted.
 // Comments:
 //                      Characters in a page form a "stream", inside the stream, each character has an index.
 //                      We will use the index parameters in many of FPDFTEXT functions. The first character in the page
 //                      has an index value of zero.
 //
 DLLEXPORT int STDCALL FPDFText_CountChars(FPDF_TEXTPAGE text_page);
 
 // Function: FPDFText_GetUnicode
 //                      Get Unicode of a character in a page.
-// Parameters: 
+// Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      index           -       Zero-based index of the character.
 // Return value:
 //                      The Unicode of the particular character.
 //                      If a character is not encoded in Unicode and Foxit engine can't convert to Unicode,
 //                      the return value will be zero.
 //
 DLLEXPORT unsigned int STDCALL FPDFText_GetUnicode(FPDF_TEXTPAGE text_page, int index);
 
 // Function: FPDFText_GetFontSize
 //                      Get the font size of a particular character.
-// Parameters: 
+// Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      index           -       Zero-based index of the character.
 // Return value:
 //                      The font size of the particular character, measured in points (about 1/72 inch).
 //                      This is the typographic size of the font (so called "em size").
 //
 DLLEXPORT double STDCALL FPDFText_GetFontSize(FPDF_TEXTPAGE text_page, int index);
 
 // Function: FPDFText_GetCharBox
 //                      Get bounding box of a particular character.
-// Parameters: 
+// Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      index           -       Zero-based index of the character.
 //                      left            -       Pointer to a double number receiving left position of the character box.
 //                      right           -       Pointer to a double number receiving right position of the character box.
 //                      bottom          -       Pointer to a double number receiving bottom position of the character box.
 //                      top                     -       Pointer to a double number receiving top position of the character box.
 // Return Value:
 //                      None.
 // Comments:
 //                      All positions are measured in PDF "user space".
@@ skipping 22 matching lines @@
 // Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      start_index     -       Index for the start characters.
 //                      count           -       Number of characters to be extracted.
 //                      result          -       A buffer (allocated by application) receiving the extracted unicodes.
 //                                                      The size of the buffer must be able to hold the number of characters plus a terminator.
 // Return Value:
 //                      Number of characters written into the result buffer, including the trailing terminator.
 // Comments:
 //                      This function ignores characters without unicode information.
-//                      
+//
 DLLEXPORT int STDCALL FPDFText_GetText(FPDF_TEXTPAGE text_page, int start_index, int count, unsigned short* result);
 
 // Function: FPDFText_CountRects
 //                      Count number of rectangular areas occupied by a segment of texts.
 // Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      start_index     -       Index for the start characters.
 //                      count           -       Number of characters.
 // Return value:
 //                      Number of rectangles. Zero for error.
@@ skipping 24 matching lines @@
 //                      Extract unicode text within a rectangular boundary on the page.
 // Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
 //                      left            -       Left boundary.
 //                      top                     -       Top boundary.
 //                      right           -       Right boundary.
 //                      bottom          -       Bottom boundary.
 //                      buffer          -       A unicode buffer.
 //                      buflen          -       Number of characters (not bytes) for the buffer, excluding an additional terminator.
 // Return Value:
-//                      If buffer is NULL or buflen is zero, return number of characters (not bytes) needed,
-//                      otherwise, return number of characters copied into the buffer.
+//                      If buffer is NULL or buflen is zero, return number of characters (not bytes) of text present within
+//                      the rectangle, excluding a terminating NUL.  Generally you should pass a buffer at least one larger
+//                      than this if you want a terminating NUL, which will be provided if space is available.
+//                      Otherwise, return number of characters copied into the buffer, including the terminating NUL
+//                      when space for it is available.
+// Comment:
+//                      If the buffer is too small, as much text as will fit is copied into it.
 //
-DLLEXPORT int STDCALL FPDFText_GetBoundedText(FPDF_TEXTPAGE text_page,double left, double top, 
+DLLEXPORT int STDCALL FPDFText_GetBoundedText(FPDF_TEXTPAGE text_page,double left, double top,
                                                                                           double right, double bottom,unsigned short* buffer,int buflen);
 
 
 // Flags used by FPDFText_FindStart function.
 #define FPDF_MATCHCASE      0x00000001          //If not set, it will not match case by default.
 #define FPDF_MATCHWHOLEWORD 0x00000002          //If not set, it will not match the whole word by default.
 
 // Function: FPDFText_FindStart
 //                      Start a search.
 // Parameters:
@@ skipping 49 matching lines @@
 //                      handle          -       A search context handle returned by FPDFText_FindStart.
 // Return Value:
 //                      None.
 //
 DLLEXPORT void STDCALL FPDFText_FindClose(FPDF_SCHHANDLE handle);
 
 // Function: FPDFLink_LoadWebLinks
 //                      Prepare information about weblinks in a page.
 // Parameters:
 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.
-// Return Value:        
+// Return Value:
 //                      A handle to the page's links information structure.
 //                      NULL if something goes wrong.
 // Comments:
 //                      Weblinks are those links implicitly embedded in PDF pages. PDF also has a type of
 //                      annotation called "link", FPDFTEXT doesn't deal with that kind of link.
 //                      FPDFTEXT weblink feature is useful for automatically detecting links in the page
 //                      contents. For example, things like "http://www.foxitsoftware.com" will be detected,
 //                      so applications can allow user to click on those characters to activate the link,
 //                      even the PDF doesn't come with link annotations.
 //
@@ skipping 39 matching lines @@
 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.
 //                      link_index      -       Zero-based index for the link.
 //                      rect_index      -       Zero-based index for a rectangle.
 //                      left            -       Pointer to a double value receiving the rectangle left boundary.
 //                      top                     -       Pointer to a double value receiving the rectangle top boundary.
 //                      right           -       Pointer to a double value receiving the rectangle right boundary.
 //                      bottom          -       Pointer to a double value receiving the rectangle bottom boundary.
 // Return Value:
 //                      None.
 //
-DLLEXPORT void STDCALL FPDFLink_GetRect(FPDF_PAGELINK link_page, int link_index, int rect_index, 
+DLLEXPORT void STDCALL FPDFLink_GetRect(FPDF_PAGELINK link_page, int link_index, int rect_index,
                                                                                 double* left, double* top,double* right, double* bottom);
 
 // Function: FPDFLink_CloseWebLinks
 //                      Release resources used by weblink feature.
 // Parameters:
 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.
 // Return Value:
 //                      None.
 //
 DLLEXPORT void STDCALL FPDFLink_CloseWebLinks(FPDF_PAGELINK link_page);
 
 
 #ifdef __cplusplus
 };
 #endif
 
 #endif//_FPDFTEXT_H_