Chilkat C++ API Lowercase Methods Returning “const char *”

In any Chilkat C++ class, there are two alternatives for methods that return a string, and for string properties. The first alternative is to return the string in an output-only “CkString &” in the final argument. The second alternative is to return a “const char *” directly. For example, the CkSFtp class has the following:

	// A property named "HostKeyFingerprint"
	void get_HostKeyFingerprint(CkString &str);
	const char *hostKeyFingerprint(void);

	// The "ReadFileText" method
	bool ReadFileText(const char *sftpHandle, int numBytes, const char *charset, CkString &outStr);
	const char *readFileText(const char *sftpHandle, int numBytes, const char *charset);

The same convention is used for the Unicode (wchar_t) version of the API, as well as the “C” API’s

	// In the CkSFtpW class:

	void get_HostKeyFingerprint(CkString &str);
	const wchar_t *hostKeyFingerprint(void);

	bool ReadFileText(const wchar_t *sftpHandle, int numBytes, const wchar_t *charset, CkString &outStr);  
	const wchar_t *readFileText(const wchar_t *sftpHandle, int numBytes, const wchar_t *charset);

	// In the "C" API

	void CkSFtp_getHostKeyFingerprint(HCkSFtp cHandle, HCkString retval);  
	const char *CkSFtp_hostKeyFingerprint(HCkSFtp cHandle);

	BOOL CkSFtp_ReadFileText(HCkSFtp cHandle, const char *sftpHandle, int numBytes, const char *charset, HCkString outStr);  
	const char *CkSFtp_readFileText(HCkSFtp cHandle, const char *sftpHandle, int numBytes, const char *charset);

Important: The lowercase alternative that returns a “const char *” is returning a pointer to internal memory that is not permanent. Your application should make use of it immediately and then discard the pointer. If the string is needed for a longer amount of time, then it should be copied to memory owned and controlled by the application, or the upper-case alternative using CkString should be used instead. If an application keeps a “const char *” pointer and continues to make additional calls on the same Chilkat object instance, the memory pointed to by the “const char *” could change.