[Gambas-devel] EXTERN Calls

[Benoit Minisini]

On Monday 20 March 2006 21:21, Scott, Vince wrote:
> Hello,
>
> I have successfully been able to make a small C library with a couple of
> functions and call them from Gambas. One does nothing more than pass
> back a number when I call it.
>
> int Test()
> {
>   return 5;
> }
>
> ...pretty simple.
>
> The second two functions I want to pass a pointer and get back data but
> cannot get them to work. I don't understand how to set them up to call
> them from Gambas.
>
> Here are my simple 'C' functions...
>
> 1.) Sample 1
>
>
> int GetName(char* pName)
> {
>   sprintf(pName, "%s", "TEST");
>
>   return 0;
> }
>
> AND
>
> 2.) Sample 2
>
> char* GetAName()
> {
>   Char* buf = malloc(5);
>
>   sprintf(buf, "%s", "TEST");
>
>   return buf;
>
> }
>
> How do I set these up to make calls in Gambas?
>
> Here is what I did:
>
> 1.) Sample 1
>
> Extern GetName(ptr AS Pointer) AS Integer IN "libtest"
>
> Public Sub Test1()
>
>   Dim ret   AS Ingteger
>   Dim ptr   AS Pointer
>   Dim sTest AS String
>
>   ptr = Alloc(sTest, 5)
>
>   ret = GetName(ptr)
>
>   Message("String= " & sTest)
>
>   Free(ptr)
>
> End
>
> 2.) Sample 2
>
> Extern GetAName() AS Pointer IN "libtest"
>
> Public Sub Test2()
>
>   Dim ret   AS Ingteger
>   Dim ptr   AS Pointer
>   Dim sTest AS String
>
>   ptr = GetAName()
>
>   sTest = StrPtr(ptr)
>
>   Message("String= " & sTest)
>
> End
>
> Both of these calls I get nothing back...or I don't know how to access
> it.
>
> Thanks,
> Vince
>
>

Here are the rules for sending and receving strings from a C function...

1) Passing a string to a C function

1.1) If the C function *does* *not* *modify* the string, you can use the 
String datatype:

  EXTERN PrintName(sStr AS String)

1.2) If the C function modifies the string (i.e. the contents the pointer 
points at), then you must create a buffer and use the Pointer datatype:

  EXTERN GetName(ptr AS Pointer)

  DIM pBuf AS Pointer

  pBuf = Alloc(X) ' X is the length of the string + 1
  GetName(pBuf)

Then, to get the string, you use StrPtr(), that will return the string located 
at pBuf. The name 'StrPtr' is maybe not very well chosen. If somebody has a 
better idea...

Do not forget to free the buffer, once you have done with it.

  Free(pBuf)

2) Getting a string from a C function

2.1) The string life is managed by the C function. Then the extern function 
must be declared as returning a String.

  EXTERN ReturnName() AS String

The string will be copied before being returned.

2.2) The string life is not managed by the C function, i.e. you allocate a 
buffer in the function for the string, or you return a constant string.

Then the extern function must be declared as returning a Pointer.

  EXTERN ReturnName() AS Pointer

You can use StrPtr() to get the string located at the returned memory address.

If the C function has allocated the string before returning it, you can use 
Free() to free it.

Note that StrPtr() will check that the pointer is valid before returning the 
string.

I hope things are clearer now. :-)

Regards,

-- 
Benoit Minisini