More API questions...

[sevensilly]

As an exercise, I'm converting a small console app I wrote in C# for an SNMP client which uses WinSNMP API. Reference to API:

http://msdn.microsoft.com/en-us/library/aa379207(VS.85).aspx

The first function that the client has to call is SnmpStartup which is defined as:

SNMPAPI_STATUS SnmpStartup(
  __out  smiLPUINT32 nMajorVersion,
  __out  smiLPUINT32 nMinorVersion,
  __out  smiLPUINT32 nLevel,
  __out  smiLPUINT32 nTranslateMode,
  __out  smiLPUINT32 nRetransmitMode
);

The function takes an smiLPUINT32 type for all its parameters (which I later learn is a pointer to an smiUINT32).

When I initially wrote my code, I declared 5 smiLPUINT32 variables (representing each parameter) which I passed to the function. At run time, I got a run time error indicating the pointers had not been initialized which is understandable.

It wasn't until I searched around for other C++ samples did I learn that the library has defined an smiUINT32 type and that the proper way to call this function is to declare 5 smiUINT32 variables each representing a parameter then pass them by reference like so:

smiUINT32 nMajorVersion;
smiUINT32 nMinorVersion;
smiUINT32 nLevel;
smiUINT32 nTranslateMode;
smiUINT32 nRetransmitMode;

SNMPAPI_STATUS result;
result = SnmpStartup(&nMajorVersion, &nMinorVersion, &nLevel, &nTranslateMode, &nRetransmitMode);

I can see that because the paramaters are annoted with __out that they should be passed by reference. The part I'm confused about is knowing the datatype I should be passing (in this case smiUINT32). Nowhere in the WinSNMP API reference does it document such a type even exists?

[guestgulkan]

If a windows API function needs a particular type then windows has a declaration/definition for that type.

sevensilly wrote:

The part I'm confused about is knowing the datatype I should be passing (in this case smiUINT32). Nowhere in the WinSNMP API reference does it document such a type even exists?

That isn't true. If you look at MSDN (or if you are using MSVC, use the help) you will find it there.
If you need info on a particular windows function/structure/ or compiler/linker error message
it is all in MSDN ( or the Visual Studio help).

[sevensilly]

Thanks for responding, guestgulkan. I'm not sure I understand the first part to your response.

Anyways, I've searched MSDN for they keyword "smiUINT32" and have found no articles exclusively on use of the type.

Here is a link to the SnmpStartup function:

http://msdn.microsoft.com/en-us/library/aa378273(VS.85).aspx

I guess what I'm asking is how does one extrapolate out of looking at this page alone that the function parameters have to be of type smiUINT32 and that such a type even exists?

Here are the notes about each parameter:

Parameters
nMajorVersion [out] 
Pointer to an unsigned long integer variable to receive the major version number of the WinSNMP API that the implementation supports. For example, to indicate that the implementation supports WinSNMP version 2.0, the function returns a value of 2.

nMinorVersion [out] 
Pointer to an unsigned long integer variable to receive the minor version number of the WinSNMP API that the implementation supports. For example, to indicate that the implementation supports WinSNMP version 2.0, the function returns a value of 0.

nLevel [out] 
Pointer to an unsigned long integer variable to receive the highest level of SNMP communications the implementation supports. Upon successful return, this parameter contains a value of 2. For a description of level 2 support, see Levels of SNMP Support.

nTranslateMode [out] 
Pointer to an unsigned long integer variable to receive the default translation mode in effect for the implementation. The translation mode applies to the implementation's interpretation of the entity parameter that the WinSNMP application passes to the SnmpStrToEntity function. The translation mode also applies to the string parameter that the WinSNMP application passes to the SnmpStrToContext function. This parameter can be one of the following values.  

Sure, they tell you that they're pointers to a long int variable, but how do I know that its implementation is type smiUINT32? Hope that makes sense.

[guestgulkan]

If the API function asks for a parameter of a particular type, then you simply provide an object of that type (or an implicitely convertable equivalent type)
- because the WINAPI has a definition for that type - all you need
to do is include the appropriate API header file to get the type declaration/ structure members
(maybe I'm not explaining it well).

Most of the typenames used in windows are typedefs for variaous API structures, or other types.
If you want to find the original type/structure members/ and you use Visual Studio, just use intellisense or check the appropriate header file.

An experienced user of windows could actually guess what the original type is:

UINT is Unsigned INTeger.
LP is Long Pointer

LPUINT32 is a Long Pointer to 32 bit Unsigned INTeger.

Here are a few lines from the winsnmp.h header file:

/* SNMP-related types */
#if ULONG_MAX == 4294967295U
typedef signed long      smiINT,           FAR *smiLPINT;
typedef smiINT           smiINT32,         FAR *smiLPINT32;
typedef unsigned long    smiUINT32,        FAR *smiLPUINT32;

[sevensilly]

Thanks guestgulkan.

It wasn't a question of how the types are declared and passed to the function- these are things I already knew. I also understand the concept of typeref/synonyms. The point I was trying to make is let's say hypothetically the synonym used for the long integer pointer (smiLPUINT32) was something more ambiguous like "smiGIBBERISH."How else would I know to pass a reference to an smiUINT32?

I guess this is where I would have to open up the header file to figure out its original type? Is it common practice/requirement to view the header files when using API functions? If so I think my mistake is thinking that the MSDN reference should be enough to provide you with all the information that you need.

[Incubbus]

Hmm... The typedef of the smiGIBBERISH has the advantage, that you know what it is used for from the name... so you does not need to bother wether it may be int or long or GIBBERISH^2 ...
Also... when changes are made u could just create GIBBERISH and do not have to care about, whether they change it to another data type later on...

(just hold the mouse bottom over the type {in vs})

[sevensilly]

Thanks for responding, Incubbus.

I think you misunderstood my hypothetical situation.

Say the header file looked like this instead:

typedef unsigned long    smiUINT32,        FAR *smiGIBBERISH;

WITHOUT looking at the header file, how would one know that smiGIBBERISH is a pointer let alone a pointer to an smiUINT32 type? Is there something in Visual Studio that would give us this information or must you look in the header file?

[Incubbus]

I don´t know what smi is for... but maybe something that makes that clear if your write it out...

Or - in Visual Studio - You can hold the mouse over the type identifier e.g.

smiUINT32

and it will show the line You posted above (as I already mentioned :P)...

[sevensilly]

Thanks Incubbus! Good tip, I misunderstood you the first time.