Why is a Pointer to a Return Value put in the Method Call?

[swhite]

Code: Select all

#dCLogFile             = "KardLiveVFP05.log"
#CLSCTX_INPROC_SERVER  = $01

Macro DEFINE_GUID(Name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)
  Global Name.GUID
  
  Name\Data1    = l
  Name\Data2    = w1
  Name\Data3    = w2
  Name\Data4[0] = b1
  Name\Data4[1] = b2
  Name\Data4[2] = b3
  Name\Data4[3] = b4
  Name\Data4[4] = b5
  Name\Data4[5] = b6
  Name\Data4[6] = b7
  Name\Data4[7] = b8
EndMacro


DEFINE_GUID(CLSID_KardAuth, $8DC6BA5D, $6861, $4F0A, $A0, $80, $7D, $ED, $CC, $97, $C1, $0F)
DEFINE_GUID(IID_KardAuth,   $4C791FAF, $8649, $462D, $A9, $3A, $18, $5F, $95, $C2, $DC, $0E)

Interface KardAuth Extends IDispatch
  Prepare110_115(String.p-bstr, String.p-bstr, ReturnValue.i)
  Prepare130(String.p-bstr, String.p-bstr, ReturnValue.i)
EndInterface

Structure Client
   Len.i
   Sent.s
   Rcvd.s
   SendEnq.b
   Eot.b
   Date.i
   IPAddr.s
EndStructure


Global gcStartIn.s
gcStartIn = GetCurrentDirectory()
NewMap lmEventClnt.Client()

Define *lnReturnPtr,*loVFP.KardAuth

If *loVFP\Prepare110_115(lcTxt, gcStartIn+#dCLogFileB, @*lnReturnPtr) = #S_OK
     lmEventClnt(lcCID)\Sent = PeekS(*lnReturnPtr,-1,#PB_Unicode)
     SysFreeString_(*lnReturnPtr)
EndIf

I am trying to understand some code originally developed by another programmer. I have only extracted the relevant code from a much larger project. The PB codes is using a Visual FoxPro COM Object. The COM object takes two string parameters and returns a string value. The part I do not understand is why ReturnValue.i is included in the method call when the actual COM object only has two string parameters. In the code above you can see that the ReturnValue.i is actually a pointer to the string returned from the COM object.

This code works perfectly and has done for years but what I want to know is why the pointer to the returned string is passed as a parameter in the method call.

Simon

[Shield]

It's an output parameter. If the function returned the pointer to the string directly,
it couldn't also return an error code. This is a common workaround in languages that
don't have advanced error handling capabilities such as exceptions (or when using them is inappropriate).

[swhite]

I understand what you are saying but the question I have is how would I know to put the parameter in the method call. Is there anywhere in Purebasic where this is discussed.

Thanks,
Simon

[Shield]

Still not quite sure I get what you mean exactly:

the "how" and "why" depends on the API you are dealing with and has nothing to do with PB per se,
you you'd have to read the API documentation to know whether a function requires you to specify an output parameter or not.

[swhite]

So basically I need to find the documentation about MS COM Objects and see how it should be handled.

Thanks,
Simon

[Shield]

Exactly.