API Calls in C++

[Lars Uffmann]

Hi!

I have a closed-source software that comes with an API, and I can't seem
to understand how to define the API functions so that my program will
actually try to access the API.

What is needed to successfully access an API in C++? Just a correct
function header definition and the running application that provides the
programming interface?

The accompanying examples (visual basic only) came with this header file:
/* ********************** */
#ifdef _WIN32
#define CCONV _stdcall
#define NOMANGLE
#else
#define CCONV FAR PASCAL _export
#define NOMANGLE EXTERN_C
#endif

NOMANGLE int CCONV UplinkUserCommand( const char *dest_name_ptr,
const char *cmd_name_ptr,
const unsigned char *cmd_data_ptr,
unsigned long len_of_cmd_data );
/* ********************** */

If I just include that, however, the linker complains about a missing
reference. So does that mean I need the dll for this api at link time?

Grateful for any tips!

Lars

[Mike Wahler]

"Lars Uffmann" <ar**@nurfuerspam.dewrote in message
news:6b*************@mid.dfncis.de...

Hi!

I have a closed-source software that comes with an API, and I can't seem
to understand how to define the API functions so that my program will
actually try to access the API.

What is needed to successfully access an API in C++? Just a correct
function header definition and the running application that provides the
programming interface?

Usually an API (aka 'library') is provided with headers to include
in your source, along with a library file containing compiled code
that you link with your executable.

>
The accompanying examples (visual basic only) came with this header file:
/* ********************** */
#ifdef _WIN32
#define CCONV _stdcall
#define NOMANGLE
#else
#define CCONV FAR PASCAL _export
#define NOMANGLE EXTERN_C
#endif

NOMANGLE int CCONV UplinkUserCommand( const char *dest_name_ptr,
const char *cmd_name_ptr,
const unsigned char *cmd_data_ptr,
unsigned long len_of_cmd_data );
/* ********************** */

Somewhere there needs to be a file (either source or compiled)
that contains the implementation of the function 'UplinkUserCommand()'.
This is usually a file called an 'object file' or 'library file'
(compiled code). Include it in the list of files submitted to your
linker. If the source is provided, then of course it must first be
compiled as well.

>
If I just include that, however, the linker complains about a missing
reference. So does that mean I need the dll for this api at link time?

Some kind of library, might or might not be a shared library (known
as 'DLL' in Windows-Land).

Did not this package provide any documentation?

-Mike

[Lars Uffmann]

X-Posted to gnu.g++.help, F'Up set also

Mike Wahler wrote:

Usually an API (aka 'library') is provided with headers to include
in your source, along with a library file containing compiled code
that you link with your executable.

Well - the headers are there, the library file is a *.lib, apparently
compiled in Visual C++. Are such library-files compiler-independant
formatted?

Somewhere there needs to be a file (either source or compiled)
that contains the implementation of the function 'UplinkUserCommand()'.

Yes of course - I was expecting that this was the dll-files in
%WINDIR%\system32 - however I have no idea how to tell the linker to
look for the function in a dll (Only now occured to me, because I have
used dlls before, but those abode by a name schema so that I could use
-lxerces for example). Guess I will have to ask in a gnu newsgroup?

This is usually a file called an 'object file' or 'library file'
(compiled code). Include it in the list of files submitted to your
linker. If the source is provided, then of course it must first be
compiled as well.

I have the *.lib from Visual C++ (I suppose thats VC++'s *incompatible*
equivalent of gnu's .a object files?) and the *.dll files. Can I use the
dll-files for linking? From what I know it should be possible... Now if
I only knew how to tell that to my linker...

Best Regards & Thanks for the answers so far,

Lars

[Paavo Helde]

Lars Uffmann <ar**@nurfuerspam.dekirjutas:

Hi!

I have a closed-source software that comes with an API, and I can't
seem to understand how to define the API functions so that my program
will actually try to access the API.

What is needed to successfully access an API in C++? Just a correct
function header definition and the running application that provides
the programming interface?

The accompanying examples (visual basic only) came with this header
file: /* ********************** */
#ifdef _WIN32
#define CCONV _stdcall
#define NOMANGLE
#else
#define CCONV FAR PASCAL _export
#define NOMANGLE EXTERN_C
#endif

NOMANGLE int CCONV UplinkUserCommand( const char *dest_name_ptr,
const char
*cmd_name_ptr,
const unsigned char
*cmd_data_ptr,
unsigned long
len_of_cmd_data );
/* ********************** */

If I just include that, however, the linker complains about a missing
reference. So does that mean I need the dll for this api at link time?

Note that the behavior of linkers and specific platforms is off topic in
this group. I just make some general comments applicable to most cross-
compiler cases (I don't know the gnu details anyway).

From your later posts I gather that you are trying to link a VC++-
compiled library with a gcc-compiled application, in Windows platform,
right?

In case of C interface you should be able to do that. In case of C++
interface this is undefined behavior, meaning that it might even work,
because the function signature seems quite C-like. From your post it is
hard to tell whether your particular DLL actually uses C or C++
interface. Note that if you manage to link the code it does not
necessarily mean it will work.

Windows-specific: the function implementation is in the .DLL (or .LIB
file for static library), but one has to link with the corresponding .LIB
file in any case. The .DLL must be present at run-time only.

The first thing to do is to look up the actual exported function name
inside the DLL (with Dependency Walker tool, for example) and see if it
is mangled or not. Then you have correctly declare the function for your
code (possibly writing your own declaration) and correctly link to the
..LIB file. The _stdcall thing may complicate the issues. The details are
far too off-topic, when you have found out the exact exported name inside
the DLL you should ask a GNU group. Or you could ask help from the DLL
provider, of course (though they might not necessarily know anything
about GNU or g++).

A correct way to use a C++ interface from another implementation is to
write a wrapper library and compile it with the same compiler (and
version, and compile flags, etc) than the original library. The wrapper
has to provide a C interface instead, which can be called from code
compiled by other compilers (C ABI is standardized, more or less, for a
given platform, which is not the case for C++ ABI).
hth
Paavo

[Lars Uffmann]

Paavo Helde wrote:

Note that the behavior of linkers and specific platforms is off topic in
this group.

"Noted" even before you commented on it, thus the follow-up. But I
wasn't aware of the general way to define API calls in C++, which is
pretty on-topic here.

From your later posts I gather that you are trying to link a VC++-
compiled library with a gcc-compiled application, in Windows platform,
right?

Yup. I wish Microsoft had never started messing around with C++, then
people wouldn't be using it *g*

In case of C interface you should be able to do that. In case of C++
interface this is undefined behavior, meaning that it might even work,
because the function signature seems quite C-like. From your post it is
hard to tell whether your particular DLL actually uses C or C++
interface.

Ouch. TBH I have no idea whether the library is C or C++. I'd have to
ask the developers. How comes he behaviour or linking vs. a dll created
with another compiler is undefined when that is written in C++?

Windows-specific: the function implementation is in the .DLL (or .LIB
file for static library), but one has to link with the corresponding .LIB
file in any case. The .DLL must be present at run-time only.

Ouch. That's what I thought & feared. But - from what you're saying, I
gather that it should be possible to link against VC++ lib-files from
other compilers?

The first thing to do is to look up the actual exported function name
inside the DLL (with Dependency Walker tool, for example) and see if it
is mangled or not.

Thank you for this - especially the tool name, I am doing some web
research on that now :)

compiled by other compilers (C ABI is standardized, more or less, for a
given platform, which is not the case for C++ ABI).

Okay, that answers my above question about undefined behaviour. Thanks
again.

I'll continue to post in gnu.g++.help once I find out more.

Best Regards,

Lars

[Paavo Helde]

Lars Uffmann <ar**@nurfuerspam.dekirjutas:

Paavo Helde wrote:

[...]

>

>In case of C interface you should be able to do that. In case of C++
interface this is undefined behavior, meaning that it might even
work, because the function signature seems quite C-like. From your
post it is hard to tell whether your particular DLL actually uses C
or C++ interface.

Ouch. TBH I have no idea whether the library is C or C++. I'd have to
ask the developers. How comes he behaviour or linking vs. a dll
created with another compiler is undefined when that is written in
C++?

The library can be implemented, but what is important is the API
interface which can still be C. This is achieved by declaring API
functions extern "C". From the #ifdef snippet from an earlier post I got
a feeling that extern "C" might probably not be used in _WIN32 branch, so
I was not sure if this is the case or not.

>

>Windows-specific: the function implementation is in the .DLL (or .LIB
file for static library), but one has to link with the corresponding
.LIB file in any case. The .DLL must be present at run-time only.

Ouch. That's what I thought & feared. But - from what you're saying, I
gather that it should be possible to link against VC++ lib-files from
other compilers?

Yes, if they are using C-style interface functions.

>

>The first thing to do is to look up the actual exported function name
inside the DLL (with Dependency Walker tool, for example) and see if
it is mangled or not.

Thank you for this - especially the tool name, I am doing some web
research on that now :)

OK. If the function name exported by DLL is just UplinkUserCommand or
_UplinkUserCommand, then it's C ABI and should be callable from other
compilers. If its something like UplinkUserCommand@24, then it is the
__stdcall ABI and the calling compiler has to support this kind of
calling convention. If it is like ??4UplinkUserCommand@@QAEAAV01@ABV01@@Z
or you can see the actual parameter list in the Dependency Walker, then
it is C++ and you are on your own. You might be able to call the function
by using the mangled name and declaring this as extern "C", but this is
not guaranteed to work.

hth
Paavo

[Lars Uffmann]

One solution (and one that I can definitely live with) was to load the
DLL at runtime and extract the functions entry point, as described in
http://en.wikipedia.org/wiki/Dynamic..._and_C.2B.2B_2
In my case, this resulted in code like this:

#include <windows.h>
#include <stdio.h>

// DLL function signature
typedef int (*_AddHeaderAndUplinkCommand)(const char *, const char *,
const char *, const unsigned char *, unsigned long);
_AddHeaderAndUplinkCommand AddHeaderAndUplinkCommand

HINSTANCE hinstLib;

int loadAPIFunctions()
{
hinstLib = LoadLibrary("myLibrary.dll");
if (hinstLib == NULL) {
printf("ERROR: unable to load DLL\n");
return 1;
}

// Get function pointer
AddHeaderAndUplinkCommand =
(_AddHeaderAndUplinkCommand)GetProcAddress(hinstLi b,
"AddHeaderAndUplinkCommand");
if (AddHeaderAndUplinkCommand == NULL) {
printf("ERROR: unable to find DLL function\n");
FreeLibrary(hinstLib);
return 1;
}

// Unload DLL file
FreeLibrary(hinstLib); // not sure if this is a good idea if
the function is still gonna be used... Any comments?

return 0;
}
I'm currently not using the FreeLibrary call at this point in the
application, rather before exiting. Anyways this works very well for
me :)