================================================================================
PAGE 61
================================================================================

$(GEVISOFTSDKPATH) \$(TargetName) $(TargetExt)
 NOTICE
Pleasemakesurethatyouselectthecorrect configuration whensettingproperties. Bestprac-
ticeistoadopttheGeViSoft settings toAllConfigurations
 NOTICE
PleasenoticethatVisualStudioreferstoenvironment variables intheform$(VAR) whereas Win-
dowsusesthe%VAR% notation. Takethisintoaccount ifyouusetheGEVISOFTSDKPATH var-
iable.
VisualStudio2010,C++
Thefollowing guideissuitable forconsole projects orMFCprojects. Ifyouwish
tobuildWindows Forms orC++/CLI applications moreconfigurations mightbe
necessary.
1.)AddGeViSoft’s headerandcppfilestoyourproject.
(YoucandothisbydragginganddroppingtheGeViScopeSDK\Include folderandtheGeV-
iSoftSDK\Include folderfrom%GEVISOFTSDKPATH%\Examples\VS2010CPP toyour
project.
2.)AddtheSDK’sincludefilestoyourprojectbyadding
$(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViScopeSDK\Include
and
$(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViSoftSDK\Include
toyourConfiguration Properties ->VC++Directories ->IncludeDirectories
3.)AddtheSDK’slibraryfilestoyourprojectbyadding
$(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViScopeSDK\lib
and

================================================================================
PAGE 62
================================================================================

$(GEVISOFTSDKPATH) \Examples\VS2010CPP\GeViSoftSDK\lib
toyourConfiguration Properties ->VC++Directories ->LibraryDirectories
4.)Intheproject’sproperties TABConfiguration Properties ->Linker->Input->Additional
Dependencies addGeViProcAPI.lib andGscActions.lib
5.)MakesurethatyouroutputfilecanfindthepathtoGeViProcAPI andGscActions DLLs.
Itisrecommended tosetConfiguration Properties ->Linker->General->OutputFileto
$(GEVISOFTSDKPATH) \$(ProjectName).exe orcopytheDLLsintotheapplication’s folder.
6.)SettheConfiguration Properties ->Debugging ->Command toyourexecutables name:
$(GEVISOFTSDKPATH) \$(TargetName) $(TargetExt)

================================================================================
PAGE 63
================================================================================

Common Tasks
Thischapterdescribes severalcommontasksyoumightneedtocarryoutduringyourdevel-
opment.
Thesearedescribed inpseudocodeandC++.Foradescription ofthe.NetAPIseechapter
C#and.Netspecifics.
Connecting toaGeViServer
ThefirstexampleshowsyouhowtoconnecttoaGeViServer byusingtheflatAPIcallsfrom
GeViProcAPI. Thesecondandrecommended methodshowsyouhowtoestablishthecon-
nectionwiththehelpofaGeViAPIClient object.
Connecting usingGeViProcAPI calls
Pseudo code
1.Declareadatabasehandle
2.Encryptthepassword string
3.CreatearemotedatabaseobjectinsidetheDLL
4.ConnecttothedatabaseobjectcreatedinsidetheDLL
C++, direct GeViProcAPI calls:
//declare astringtoholdthepassword hash
//(32byte+'\0')
charencodedPassword [33];

================================================================================
PAGE 64
================================================================================

//declare adatabase handle
GeViAPI_ Namespace::HGeViDatabase database;
//encodethepassword
GeViAPI_ EncodeString (encodedPassword, "masterkey",
sizeof(encodedPassword));
//createaremotedatabase objectinsidethe DLL
//toaccessaGeViSoft database
GeViAPI_ Database_ Create(database, "localhost" ,
"127.0.0.1" ,"sysadmin" ,
encodedPassword, "","");
if(database) //database successfully created
{
//Connect functions result
TConnectResult result;
//Connect tothedatabase object.
GeViAPI_ Database_ Connect(database, result,
NULL/*yourcallback here!*/,
NULL/*yourinstance here!*/);
if(result ==connectOk)
std::cout <<"Connection established!";
}
Connecting usingGeViAPIClient Objects (recommended)
Pseudo code
1.DeclareaGeViAPIClient wrapperobject
2.Declareanddefineaconnection callbackfunctiontomonitortheconnection progress(this
functionwillbecalledfrominsidetheDLLandreturnaprogressstateinitsarguments)

================================================================================
PAGE 65
================================================================================

3.Encryptthecleartextpassword
4.CreateaninstanceoftheGeViAPIClient wrapperobject
5.Callthewrapper’s connectmethod
6.CheckIftheconnectmethodreturnedasuccess
C++, GeViAPIClient calls:
1.Connection handling
//wrapper aroundaGeViAPIclientobject
GeViAPIClient* m_APIClient;
//declare astringtoholdthepassword hash
charencodedPassword [33];
GeViAPIClient::EncodePassword (encodedPassword,
"mypassword" ,
sizeof(encodedPassword) );
//createannewinstance ofthewrapper
m_APIClient =newGeViAPIClient ("MyGeViServer" ,
"127.0.0.1" ,"sysadmin" ,
encodedPassword, NULL,NULL);
if(m_APIClient)
{
//connect totheserver–ConnectProgressCB isyourcallback
TConnectResult ConnectResult =
m_APIClient- >Connect (ConnectProgressCB, this);
if(ConnectResult ==connectOk)
{
//Connection successfully established
//Doyourworkhere.
}

================================================================================
PAGE 66
================================================================================

}
2.Callbacks
//Callback function forconnect progress display
bool__stdcall ConnectProgressCB (void*Instance,
intPercentage,
intPercent100)
{
if(Instance ==NULL)
{
return(true);
}
//Callthecallback methodofyourclass
//object's instance
CYourClass* yourClass =(CYourClass*) Instance;
return( yourClass- >ConnectProgress (
Percentage, Percent100) );
}
//Yourclass’s callback
boolCYourClass::ConnectProgress (intpercentageLower,
intpercentageUpper)
{
//Dos.th.,e.g.showaProgress Ctrl.
return(true);
}
Connection Monitoring
GeViSoftoffersmethodstomonitorifyourconnection isstillestablished. Itisadvisableto
monitortheconnection fromyourapplication andtryareconnect ifitbreaksdown.
YoucanusethesendPing()methodforconnection monitoring whichreturnstrueifthecon-
nectionisstillestablished andfalseifnot.

================================================================================
PAGE 67
================================================================================

BestpracticeistocyclicallycallsendPing()fromaseparatethreadandhandletherecon-
nectionfrominsidethisthreadifnecessary.
Monitoring connections isimplemented intheSDK’sexample CPP_Mon-
itoredConnectionClient.
Monitoring aConnection
Pseudo code
1.Createaseparatethreadinsideyourapplication ifaconnection shouldbeestablished
2.Insidethisthead,DO:
a.Sendapingtotheserver
b.IFtheresultofthepingisNOTtrue:tryareconnect
c.Sleepforagiventime(e.g.10s)
3.UNTILtheconnection shouldbeterminated
C++Example
//Prerequisite:
//GeViAPIClient* m_APIClient
//mustalready becreated andconnected.
//
//Runthismethodinsideaseparate Thread!
intMonitorConnection ()
{
constintreconnectionPeriod_ in_ms=10000;
boolresult;
while(true){

================================================================================
PAGE 68
================================================================================

result=m_APIClient- >SendPing ();
if(result ==false)
{
//TODO:notifyyouruserhere.
//Tryareconnect:
m_APIClient- >Connect (YourConnectCallbackCB, this);
}
Sleep(reconnectionPeriod_ in_ms);
}
return0;
}

================================================================================
PAGE 69
================================================================================

Message Handling
Afteryouhaveestablished yourconnection youarereadytoexchange messages withthe
server.
Message Representation
Therearetwopossiblerepresentations ofmessages inGeViSoft. Theyareeitherstoredina
binaryformorasanASCIIstring.TheAPIoffersmethodstoconvertbetweenthesetworep-
resentations. ThesemethodsaredefinedintheMessageBase header,C++,andPascalfiles.
Tableofconversion methodsbetweenmessagerepresentations.
CGeV-
iMessage::ReadASCIIMessageConverts anASCIIstringintoaCGeViMessage
CGeV-
iMessage::WriteASCIIMessageConverts aCGeViMessage intoanASCIIstring
CGeViMessage::ReadBinMessage Converts abinaryrepresentation ofamessage intoaCGeV-
iMessage
CGeV-
iMessage::WriteBinMessageConverts aCGeViMessage intoitsbinaryrepresentation

================================================================================
PAGE 70
================================================================================

ActionMessages
Creating ActionMessages
Youcancreateanactionmessageintwoways.Oneisbycallingitspredefined actioncon-
structordirectly.Theotherisbyconverting anASCIIorbinaryrepresentation intoanew
actionobject.Thepredefined constructors arelocatedintheActionsheader,C++,andPas-
calfiles.
Actionscanbeconsidered aseitherbeingdirectcommands fromtheclienttotheGeViServer
tocontrolitsperipheryorasnotifications whicharesentfromtheservertotheclienttoindi-
catestatechangesoflogicalorphysicalcomponents. Incontrasttoactions,therearestate
queriesanddatabasequeries.Thesearetreatedseparately inthechapters StateQueriesand
Database Queries.
1.Example foradirectly created CustomAction message (con-
structor fromActions.h/cpp)
CGeViMessage* gevimessage =new
CActCustomAction (123,"HelloGeViSoft!" );
2.Example foraCustomAction message created fromastring
intbytesRead;
std::string buffer("CustomAction (123,\"Hello GeViSoft!\") ");
CGeViMessage* gevimessage =
CGeViMessage::ReadASCIIMessage (buffer.c_ str(),
buffer.size (),
bytesRead );
3.Example fortheASCIIoutput ofabinary action message:
//gevimessage isthebinarymessage