Unclear Documentation - PXCp_StringGetB

This Forum is for the use of Software Developers requiring help and assistance for Tracker Software's PDF-Tools SDK of Library DLL functions(only) - Please use the PDF-XChange Drivers API SDK Forum for assistance with all PDF Print Driver related topics or PDF-XChange Viewer SDK if appropriate.

Moderators: TrackerSupp-Daniel, Tracker Support, Vasyl-Tracker Dev Team, Chris - Tracker Supp, Sean - Tracker, Tracker Supp-Stefan

Post Reply
afalsow
User
Posts: 17
Joined: Thu Jun 14, 2012 1:28 pm

Unclear Documentation - PXCp_StringGetB

Post by afalsow »

From documentation:

HRESULT PXCp_StringGetB(
HPDFSTRING hString,
BYTE* buf,
DWORD* pbufLen
);

hString
[in] hString specifies the PDF string handle.

buf
[in] buf is a pointer to a buffer that receives string content presented as binary data. This parameter may be NULL.

pbufLen
[in/out] pbufLen is a pointer to variable that specifies the size of the buffer in bytes. If buf is NULL then pbufLen creates a buffer sufficient to receive the binary data.

QUESTION: But if buf is NULL, then the function creates a buffer? ....but where is that buffer? If I do not specify it, and it's created automatically, how does the developer reference the buffer? Or do I misinterpret the documentation?
Nico - Tracker Supp
User
Posts: 205
Joined: Fri May 18, 2012 8:41 pm

Re: Unclear Documentation - PXCp_StringGetB

Post by Nico - Tracker Supp »

Hi afalsow,

Thanks for your post.
QUESTION: But if buf is NULL, then the function creates a buffer? ....but where is that buffer? If I do not specify it, and it's created automatically, how does the developer reference the buffer? Or do I misinterpret the documentation?
The function always creates a buffer internally and returns a handle to that buffer which is hString.
The only difference is if you don't allocate memory for buf, you won't be able to get the string value that is in the internal buffer but you will be able to get the length of the string so that you can allocate memory for the external buffer and call this function again to get the string value.
Please let me know if you have further questions.
Thanks.

Sincerely,
wings software
User
Posts: 18
Joined: Mon Apr 23, 2012 12:38 pm

Re: Unclear Documentation - PXCp_StringGetB

Post by wings software »

Nico - Tracker Supp wrote:The function always creates a buffer internally and returns a handle to that buffer which is hString.
It may well be the case that the function creates the internal buffer for holding the string characters, but IMO it doesn't return a handle to it. If I'm not mistaken, the string handle has to be created first with PXCp_StringCreate() and released with PXCp_StringDelete() afterwards.

Jan
User avatar
Tracker Supp-Stefan
Site Admin
Posts: 17823
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: Unclear Documentation - PXCp_StringGetB

Post by Tracker Supp-Stefan »

Hello Jan,

After checkign this with one of my colleagues he says that you must allocate this buffer yourself.
If buf is NULL then pbufLen will contain the required length of the buffer, otherwise - the number of copied bytes.

Best,
Stefan
wings software
User
Posts: 18
Joined: Mon Apr 23, 2012 12:38 pm

Re: Unclear Documentation - PXCp_StringGetB

Post by wings software »

Tracker Supp-Stefan wrote:After checkign this with one of my colleagues he says that you must allocate this buffer yourself.
Stefan,

Indeed, the phrasing of my remark was a bit awkward. I was aware of the fact that with PXCpStringGetB you get a copy of the characters in your own allocated buffer. However, Nico seemed to imply that the function returns a handle to the PDFTools 'internal' string, which is not the case AFAIK.

Thanks,
Jan
User avatar
Tracker Supp-Stefan
Site Admin
Posts: 17823
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: Unclear Documentation - PXCp_StringGetB

Post by Tracker Supp-Stefan »

Hello Jan,

Maybe Nico's comment was not clear either :)

he implies that you will get "something" whether or not buf is NULL or not - but when it is NULL you will not be able to get the handle of the buffer - and will instead only receive (as the value of pbufLen) the required length of the buffer - but there won't be any bytes copied (or you actually won't have the means to access them).

Best,
Stefan
Nico - Tracker Supp
User
Posts: 205
Joined: Fri May 18, 2012 8:41 pm

Re: Unclear Documentation - PXCp_StringGetB

Post by Nico - Tracker Supp »

Hi Jan,

The handle to the string is returned when you call PXCp_CreateString. This is when memory is allocated for the string internally.
The string gets set when you call PXCp_StringSetA.
When you call PXCp_StringGetB with buffer NULL, you get the length of the string
When you call PXCp_StringGetB with a not NULL buffer, you get both the length of the string and a copy of the string into buffer.
The string gets deleted when you call PXCp_StringDelete.
I'm attaching a code example for clarification purposes:

Code: Select all

HPDFSTRING hString;
BYTE* buffer = NULL;
DWORD bufLength = 0;
HRESULT hr;
// Buffer NULL
hString = PXCp_StringCreate();
hr = PXCp_StringSetA(hString, "String1");
hr = PXCp_StringGetB(hString, NULL, &bufLength);
buffer = new BYTE[bufLength+1];
hr = PXCp_StringGetB(hString, buffer, &bufLength);
buffer[bufLength] = '\0';
hr = PXCp_StringDelete(hString);
hString = NULL;	
delete buffer;
Thanks.

Sincerely,
Post Reply