Assume I am coding in C and using CkByteData
So I call CkByteData_Create; Does that malloc a buffer for the byte data?
Assume I dont put any data into the object and I now call CkByteData_borrowData and "pass" in a buffer that I had created via malloc and filled with some byte data
The goal BTW is to now pass this CkByteData to an encryption proc
What should I do to make sure there are no memory leaks?
Should I call my "free" memory routine (opposite of malloc) on the buffer I created?
Can I just call CkByteData_Dispose and not fear that it will also try to free the buffer I provided it via my borrowData API call?
Do I need to have the following sequence to avoid memory leaks and memory issues? CkByteData_Create malloc my buffer CkByteData_borrowData and pass in the buffer (and size) I malloc'ed call encrypt call CkByteData_Clear call CkByteData_dispose free the buffer I malloc'ed?
The Chilkat API is an object-oriented API. In object-oriented programming languages, there are Chilkat classes (or objects) each of which has methods and properties. Some languages, such as "C", are not object-oriented. The general pattern for handling the object-oriented paradigm in such environments is to provide a create function that returns an opaque handle to the object, a destroy function that deletes the object via the opaque handle, and all methods/properties are functions that include the opaque handle as the 1st argument. For example:
HCkEmail email; BOOL success; ... email = CkEmail_Create(); success = CkEmail_LoadEml(email,"something.eml"); ... CkEmail_Dispose(email); ...The meaning of "opaque handle" is that your app does not need to know what it is. The only concern of your app is to make sure the handle is "released" via the method that is provided for that purpose. In this case, it's the "*_Dispose" function.
Regarding raw memory data, such as "char" or "unsigned char" arrays: When a Chilkat function returns a "const" pointer, it is a pointer to internal memory that should NOT be deleted by your application. It is memory that should be used immediately. Subsequent calls to functions on the same object instance may invalidate the "const" pointer, and certainly disposing of the object will also invalidate the pointer.
If a non-const pointer is returned, it means the memory is provided to your app, and your app is responsible for deleting it. However, the internal memory was allocated via the C++ "new" operator. For example, "char *x = new char;". I see now that this is an oversight in that a "C" program would not be able to properly free this memory. However, there are only a few instances where non-const pointers are returned. These can be avoided, and it should be possible to use methods that return "const char *" (or "const unsigned char *") and copy the memory to your own "C" buffer.
For methods that return a new object instance (i.e. a handle), these should be disposed using the "*_Dispose" function that corresponds to the object type.
The CkByteData_borrowData is such that you may provide the CkByteData object with your own memory. However, the CkByteData method will never delete it. Your app is still responsible for deleting (freeing) the memory.