inco_32.h File Reference

Interface functions for the libinco_32 dll/so. More...

#include <inco_32/indeltypes.h>
#include <inco_32/indeldefs.h>
#include <inco_32/errinco.h>
#include <windows.h>

Go to the source code of this file.

Macros
#define	INCO32_EXPORT   __declspec(dllimport)
#define	DF_KEY_INDEL_PATH_DEP   "SOFTWARE\\Indel"
#define	DF_TASK_NUMBER_OF_GPR   32
#define	DF_TASK_NUMBER_OF_FPR   32
#define	DF_TASK_NUMBER_OF_SPR   8

Functions
INCO variable reading and writing
INCO32_EXPORT uint32 WINAPI	GetVariable (const char *TargetPath, const char *ItemPath, void *Result, uint32 Length)
	Remote INCO variable read. More...
INCO32_EXPORT uint32 WINAPI	PutVariable (const char *TargetPath, const char *ItemPath, const void *Value, uint32 Length)
	Remote INCO variable write. More...
INCO variable reading and writing (type-safe)
INCO32_EXPORT uint32 WINAPI	GetVariableEx (const char *TargetPath, const char *ItemPath, uint32 IncoType, void *Value, uint32 Length)
INCO32_EXPORT uint32 WINAPI	PutVariableEx (const char *TargetPath, const char *ItemPath, uint32 IncoType, const void *Value, uint32 Length)
Remote INCO procedure call (RPC)
(see also Synchronous Calling of Asynchronous Procedures)
INCO32_EXPORT uint32 WINAPI	CallProcedure (const char *TargetPath, const char *CallProcedure, double *Result)
	Remote procedure call. More...
INCO32_EXPORT int32 WINAPI	CallProcedureEx (const char *TargetPath, const char *CallProcedure, double *SyncResult)
	Remote procedure call (extended). More...
INCO32_EXPORT uint32 WINAPI	CallProcedureExSync (const char *TargetPath, const char *CallProcedure, void *Result, uint32 BufferSize, uint32 TypeFlags)
	Remote procedure call (extended). If the procedure has an asynchronous part, the function will wait for it to complete. More...
INCO32_EXPORT uint32 WINAPI	CallProcedureExWait (const char *TargetPath, int32 Ticket, int32 TimeoutMs)
	Wait for the asynchronous part of a remote procedure call (CallProcedureEx) to finish (optionally with timeout). More...
INCO32_EXPORT uint32 WINAPI	CallProcedureExResult (const char *TargetPath, int32 Ticket, void *Result, uint32 BufferSize, uint32 TypeFlags, char *ResultName, uint32 ResultNameBufSize)
	Get the next asynchronous result (or application error) of a remote procedure call (CallProcedureEx). More...
INCO32_EXPORT uint32 WINAPI	CallProcedureExResultByName (const char *TargetPath, int32 Ticket, const char *ResultName, void *Result, uint32 BufferSize, uint32 TypeFlags)
	Get the next asynchronous named result (or application error) of a remote procedure call (CallProcedureEx). More...
Raw target memory access functions
INCO32_EXPORT uint32 WINAPI	PutBlock8 (const char *TargetPath, uint32 DestAddress, const uint8 *Data, uint32 Number)
	Write raw data in 8 byte chunks to the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlockEx8 (const char *TargetPath, uint64 DestAddress, const uint8 *Data, uint32 Number)
	Write raw data in 8 byte chunks to the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlock8 (const char *TargetPath, uint32 SourceAddress, uint8 *Data, uint32 Number)
	Reads raw data in 8 byte chunks from the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlockEx8 (const char *TargetPath, uint64 SourceAddress, uint8 *Data, uint32 Number)
	Reads raw data in 8 byte chunks from the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlock8Real (const char *TargetPath, uint32 SourceAddress, uint8 *Data, uint32 Number)
	For Indel internal use: Read 8 byte chunks of data from target by resolving breakpoints. More...
INCO32_EXPORT uint32 WINAPI	GetBlockEx8Real (const char *TargetPath, uint64 SourceAddress, uint8 *Data, uint32 Number)
	For Indel internal use: Read 8 byte chunks of data from target by resolving breakpoints. More...
INCO32_EXPORT uint32 WINAPI	PutBlock16 (const char *TargetPath, uint32 DestAddress, const uint16 *Data, uint32 Number)
	Write raw data in 16 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlockEx16 (const char *TargetPath, uint64 DestAddress, const uint16 *Data, uint32 Number)
	Write raw data in 16 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlock16 (const char *TargetPath, uint32 SourceAddress, uint16 *Data, uint32 Number)
	Read raw data in 16 bytes chungs from the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlockEx16 (const char *TargetPath, uint64 SourceAddress, uint16 *Data, uint32 Number)
	Read raw data in 16 bytes chungs from the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlock32 (const char *TargetPath, uint32 DestAddress, const uint32 *Data, uint32 Number)
	Write raw data in 32 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlockEx32 (const char *TargetPath, uint64 DestAddress, const uint32 *Data, uint32 Number)
	Write raw data in 32 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlock32 (const char *TargetPath, uint32 SourceAddress, uint32 *Data, uint32 Number)
	Read raw data in 32 bytes chungs from the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlockEx32 (const char *TargetPath, uint64 SourceAddress, uint32 *Data, uint32 Number)
	Read raw data in 32 bytes chungs from the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlock64 (const char *TargetPath, uint32 DestAddress, const uint64 *Data, uint32 Number)
	Write raw data in 64 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	PutBlockEx64 (const char *TargetPath, uint64 DestAddress, const uint64 *Data, uint32 Number)
	Write raw data in 64 bytes chungs to the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlock64 (const char *TargetPath, uint32 SourceAddress, uint64 *Data, uint32 Number)
	Read raw data in 64 bytes chungs from the target. More...
INCO32_EXPORT uint32 WINAPI	GetBlockEx64 (const char *TargetPath, uint64 SourceAddress, uint64 *Data, uint32 Number)
	Read raw data in 64 bytes chungs from the target. More...
INCO error information
INCO32_EXPORT uint32 WINAPI	GetErrorDescription (const char *TargetPath, uint32 Error, char *Description, uint32 Length)
	Convert an INCO error (see also Failures related to INCO (INdel COnnectivity)) to human readable string. More...
INCO32_EXPORT uint32 WINAPI	GetMcMessage (const char *TargetPath, const char *MessageHandlerPath, uint32 Error, char *Message, uint32 Length)
INCO32 version information
INCO32_EXPORT uint32 WINAPI	GetRevisions (const char *TargetPath, uint32 *ServerRevision, uint32 *DllRevision)
	Function to get the INCOServer and libinco_32 revisions.
Database functions (for Indel internal use)
INCO32_EXPORT uint32 WINAPI	CreateTable (const char *TargetPath, const char *TableName, const char *DatabaseName, uint32 NumberRecords, uint32 RecordSize, uint32 Flags)
INCO32_EXPORT uint32 WINAPI	DeleteTable (const char *TargetPath, const char *TableName)
INCO32_EXPORT uint32 WINAPI	PutRecord (const char *TargetPath, const char *TableName, const char *Record, void *Data, uint32 Size)
INCO32_EXPORT uint32 WINAPI	GetRecord (const char *TargetPath, const char *TableName, const char *Record, void *Data, uint32 Size)
Target functionality (for Indel internal use)
INCO32_EXPORT uint32 WINAPI	TgtCharacteristics (const char *TargetPath, uint32 *aResult)
INCO32_EXPORT uint32 WINAPI	TgtCharacteristicsEx (const char *TargetPath, uint32 *aResult, uint32 aLength)
TargetPath debugging functionality (for Indel internal use)
INCO32_EXPORT uint32 WINAPI	DbgOsPrepareLoad (const char *TargetPath)
INCO32_EXPORT uint32 WINAPI	DbgOsReset (const char *TargetPath, uint32 aFlags)
INCO32_EXPORT uint32 WINAPI	DbgTasksList (const char *TargetPath, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTasksState (const char *TargetPath, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetId (const char *TargetPath, const char *aTaskName, uint32 *aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskSetBreakpoint (const char *TargetPath, const char *aTaskName, uint32 aAddress)
INCO32_EXPORT uint32 WINAPI	DbgTaskClrBreakpoint (const char *TargetPath, const char *aTaskName, uint32 aAddress)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetBreakpoint (const char *TargetPath, uint32 aNumber, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetName (const char *TargetPath, uint32 aTaskId, char *aTaskName, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskHalt (const char *TargetPath, uint32 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskRun (const char *TargetPath, uint32 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskSingleStep (const char *TargetPath, uint32 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskRangeStep (const char *TargetPath, uint32 aTaskId, uint32 auFrom, uint32 auTo)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetGPRs (const char *TargetPath, uint32 aTaskId, uint32(*aResult)[DF_TASK_NUMBER_OF_GPR])
INCO32_EXPORT uint32 WINAPI	DbgTaskGetFPRs (const char *TargetPath, uint32 aTaskId, double(*aResult)[DF_TASK_NUMBER_OF_FPR])
INCO32_EXPORT uint32 WINAPI	DbgTaskGetSPRs (const char *TargetPath, uint32 aTaskId, uint32(*aResult)[DF_TASK_NUMBER_OF_SPR])
INCO32_EXPORT uint32 WINAPI	DbgTaskGetGPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, uint32 *aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetFPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, double *aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetSPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, uint32 *aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutGPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, uint32 aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutFPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, double aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutSPR (const char *TargetPath, uint32 aTaskId, uint32 aNumber, uint32 aValue)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetData (const char *TargetPath, uint32 aTaskId, uint32 aDataDef, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutData (const char *TargetPath, uint32 aTaskId, uint32 aDataDef, void *aData, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgCpuGetSPR (const char *TargetPath, uint32 aNumber, uint32 *aResult)
INCO32_EXPORT uint32 WINAPI	DbgCpuPutSPR (const char *TargetPath, uint32 aNumber, uint32 aValue)
INCO32_EXPORT uint32 WINAPI	DbgCpuGetDCR (const char *TargetPath, uint32 aNumber, uint32 *aResult)
INCO32_EXPORT uint32 WINAPI	DbgCpuPutDCR (const char *TargetPath, uint32 aNumber, uint32 aValue)
INCO32_EXPORT uint32 WINAPI	DbgEmeCommStatus (const char *TargetPath, uint32 *apEmeCommStatus)
INCO32_EXPORT uint32 WINAPI	DbgOsContinue (const char *TargetPath, uint32 auFlags)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetReg (const char *TargetPath, uint32 aTaskId, uint32 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength)
INCO32_EXPORT uint32 WINAPI	DbgSetWatchpoint (const char *TargetPath, uint32 auAddress, uint32 auSize, uint32 auFlags, uint32 *apAddress, uint32 *apSize)
INCO32_EXPORT uint32 WINAPI	DbgClrWatchpoint (const char *TargetPath, uint32 auAddress)
INCO32_EXPORT uint32 WINAPI	DbgTargetGetDataMulti (const char *TargetPath, uint32 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetDataMulti (const char *TargetPath, uint32 aTaskId, uint32 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetDataFromCache (const char *TargetPath, uint32 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutGdbReg (const char *TargetPath, uint32 aTaskId, const uint32 auRegister, const void *apData, uint32 auDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTasksListEx (const char *TargetPath, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTasksStateEx (const char *TargetPath, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetIdEx (const char *TargetPath, const char *aTaskName, uint64 *aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskSetBreakpointEx (const char *TargetPath, const char *aTaskName, uint64 aAddress)
INCO32_EXPORT uint32 WINAPI	DbgTaskClrBreakpointEx (const char *TargetPath, const char *aTaskName, uint64 aAddress)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetBreakpointEx (const char *TargetPath, uint32 aNumber, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetNameEx (const char *TargetPath, uint64 aTaskId, char *aTaskName, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskHaltEx (const char *TargetPath, uint64 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskRunEx (const char *TargetPath, uint64 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskSingleStepEx (const char *TargetPath, uint64 aTaskId)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetDataEx (const char *TargetPath, uint64 aTaskId, uint32 aDataDef, void *aResult, uint32 aLength)
INCO32_EXPORT uint32 WINAPI	DbgSetWatchpointEx (const char *TargetPath, uint64 auAddress, uint64 auSize, uint32 auFlags)
INCO32_EXPORT uint32 WINAPI	DbgClrWatchpointEx (const char *TargetPath, uint64 auAddress)
INCO32_EXPORT uint32 WINAPI	DbgTaskRangeStepEx (const char *TargetPath, uint64 aTaskId, uint64 auFrom, uint64 auTo)
INCO32_EXPORT uint32 WINAPI	DbgTargetGetDataMultiEx (const char *TargetPath, uint64 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetDataMultiEx (const char *TargetPath, uint64 aTaskId, uint64 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskGetDataFromCacheEx (const char *TargetPath, uint64 *apCookie, uint32 *apFlags, void *apBuffer, uint32 *apBufferLength, uint32 *apRemainingDataLength)
INCO32_EXPORT uint32 WINAPI	DbgTaskPutGdbRegEx (const char *TargetPath, uint64 aTaskId, const uint32 auRegister, const void *apData, uint32 auDataLength)
Synchronous Calling of Asynchronous Procedures - Procedure Part (for Indel internal use)
(see also Synchronous Calling of Asynchronous Procedures)
INCO32_EXPORT int32 WINAPI	CheckoutAsyncCallTicket (void)
	Called by an asynchronous procedure when an asynchronous action starts. More...
INCO32_EXPORT uint32 WINAPI	ProcedureExAddResult (int32 Ticket, const void *Result, uint32 auResultSize, uint32 auType, const char *ResultName)
	Called by an asynchronous procedure to return a result value. More...
INCO32_EXPORT uint32 WINAPI	ProcedureExAddAppError (int32 Ticket, uint32 auAppError)
	Called by an asynchronous procedure to return an application error. More...
INCO32_EXPORT void WINAPI	ReturnAsyncCallTicket (int32 Ticket)
	Called by an asynchronous procedure when an asynchronous action finishes. More...
INCO32_EXPORT int32 WINAPI	ReturnAsyncCallTicketAfterCallHasFinished (int32 aiMyTicket, int32 aiTicketToWaitFor)
	Called by an asynchronous procedure to declare an asynchronous action completed as soon as another asynchronous procedure finishes. More...
Synchronous Calling of Asynchronous Procedures (for Indel internal use)
INCO32_EXPORT void WINAPI	PushDeferredCallTicket (int32 Ticket)
	Called by a deferred CallProcedure handler to put a ticket back on libinco_32's stack. More...
INCO32_EXPORT int32 WINAPI	PopDeferredCallTicket (void)
	Called by a deferred CallProcedure handler to remove a ticket from libinco_32's stack. More...
Deprecated functions
INCO32_EXPORT uint32 WINAPI	PutBit (const char *TargetPath, uint32 Address, uint32 Number, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	GetBit (const char *TargetPath, uint32 Address, uint32 Number, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	PutOutput (const char *TargetPath, const char *Output, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	GetOutput (const char *TargetPath, const char *Output, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	PutInput (const char *TargetPath, const char *Input, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	GetInput (const char *TargetPath, const char *Input, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	PutFlag (const char *TargetPath, const char *Flag, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	GetFlag (const char *TargetPath, const char *Flag, uint32 *Value)
INCO32_EXPORT uint32 WINAPI	GetError (const char *TargetPath)
INCO32_EXPORT uint32 WINAPI	GetServerRevisionS (uint8 *aServerVersion)
	Function to get the INCOServer revision. More...

Data Transfer. Always prefer INCO over data transfer unless
you have a good reason to use the latter. Do only choose to use Data transfer is an alternative way of transferring data to and from a target. The key features of the data transfer technology are: Transfer of arbitrary sized data (e.g. 100MByte) is supported Direct data channel to the target, without having an additional task switch to another process (e.g. INCOServer). (Note that a data transfer may be performed by INCO frames - so that this statement is not always true) Data transfers are always configured/setup by the target. The target defines all properties of the transfer, such as maximum allowed transfer size, timeouts, retries, etc. A target may offer "multiple data transfer" endpoints (e.g.: One for "Fast load", one for "Customer log data", etc.) and each endpoint may allow the data to be transferred by different technologies (such as UDP, PCIe, INCO, etc.) It's the duty of the user of the libinco_32 data transfer functions to choose the right endpoint. Libinco_32 will then automatically choose the "best" transfer technology. The data transfer technology is not meant to be used just by chance... Instead: The decission to use data transfers must be done very conscious. Also the properties, such as retries, timeout, etc. must be choosen with care and must be well tested in long-durance tests. IMPORTANT : To avoid lags or even deadlocks when transferring over unreliable channels such as UDP, it is mandatory to obey the following rule: After issuing a DTReceive call, Data Transfer clients must either immediately call DTReceive again or immediately shutdown the connection via DTClose. This implies that it is not allowed to perform a DTSend directly after a DTReceive within the same thread. To illustrate the necessity of this rule, consider the following scenario: The PC wants to receive data from the target by calling DTReceive. The target replies within the timeout, so DTReceive sends an acknowledgement to the target and returns the received data to the caller. If the acknowledgement is lost, the target will run into a timeout and retransmit its reply to the PC, assuming that the PC did not receive the first transmission. Now, if the PC is not listening via DTReceive, the retransmission will never be handled, leading to subsequent retransmissions issued by the target until all retries are exhausted.
typedef uintptr	tLDTFileDescriptor
INCO32_EXPORT uint32 WINAPI	DTOpen (const char *TargetPath, const char *Endpoint, tLDTFileDescriptor *FileDescriptor)
INCO32_EXPORT void WINAPI	DTClose (tLDTFileDescriptor FileDescriptor)
INCO32_EXPORT uint32 WINAPI	DTSend (tLDTFileDescriptor FileDescriptor, const void *DataBuffer, uint32 DataLength)
INCO32_EXPORT uint32 WINAPI	DTReceive (tLDTFileDescriptor FileDescriptor, void *DataBuffer, uint32 DataBufferSize, uint32 *DataLength, int32 TimeoutMs)

Querying and modifying data transfer parameters
enum	DTCtlRequest { DTCtlForceConnect }
	Request identifiers for IncoControl(). More...
INCO32_EXPORT uint32 WINAPI	DTControl (const char *TargetPath, int32 aiRequest, void *apData, uint32 auDataLength)
INCO32_EXPORT uint32 WINAPI	DTGetBufferSizes (tLDTFileDescriptor FileDescriptor, uint32 *LocalBufferSize, uint32 *TargetBufferSize)

INIX frame dispatching functionality (for Indel internal use)
typedef uint32(WINAPI *	frameCallbackFct) (uint32 ahPlugin, const char *aIncoFrameStream, uint32 Length, char *apResponseFrameStream, uint32 *apResponseStreamLength)
INCO32_EXPORT uint32 WINAPI	IncoInitialize (void)
INCO32_EXPORT uint32 WINAPI	IncoUninitialize (void)
INCO32_EXPORT uint32 WINAPI	RegisterDispatcher (const char *apFullPluginPath, uint32 aPluginId, frameCallbackFct aProcessFramePtr)
INCO32_EXPORT uint32 WINAPI	UnregisterDispatcher (const char *apFullPluginPath)
INCO32_EXPORT uint32 WINAPI	RegisterAdditionalDispatcherByThread (const char *apFullPluginPath, uint32 aPluginId, frameCallbackFct aProcessFramePtr)
INCO32_EXPORT uint32 WINAPI	UnregisterAdditionalDispatcherByThread (const char *apFullPluginPath)
INCO32_EXPORT uint32 WINAPI	INCOSetThreadName (const char *apThreadName)
INCO32_EXPORT uint32 WINAPI	INCOGetThreadName (char *apThreadName, uint32 apThreadNameBufferLength)
INCO32_EXPORT void WINAPI	INCOClearThreadName (void)
INCO32_EXPORT uint32 WINAPI	HandleINCOFrameFromServer (int32 aiTimeout)

Querying and modifying library parameters
enum	IncoCtlRequest { IncoCtlSetTcpServerAddress, IncoCtlStartRecorder, IncoCtlStopRecorder, IncoCtlAllowTicketDelegation }
	Request identifiers for IncoControl(). More...
INCO32_EXPORT uint32 WINAPI	IncoControl (const char *TargetPath, int32 aiRequest, void *apData, uint32 auDataLength)
	Query and manipulate miscellaneous internal library state and settings. More...

Detailed Description

Interface functions for the libinco_32 dll/so.

Author

Raphael Zulliger, © INDEL AG

Version

2.00    06.08.1997-CH: * Origin.
2.01    21.02.2001-FC: - Removed obsolete calls.
                       + Added inco types, characteristics, error codes.
3.00    30.09.2003-RZ: + Added functions for (de-)initializing of the
                         inco_32.dll. Needed for compatibility with 
                         new inco_32.dll (version 3.0) for IncoServer 3.0.
3.01    10.05.2004-FC: ! Deprecated DF_KEY_INDEL_PATH (read from IncoServer).
                       + New error ER_INCO_SERVER_TOO_OLD.
3.02    03.06.2004-RZ: + Added declspec(dllexport/dllimport) needed for 
                         using this file for Windows CE (Pocket PC) programs
                       ! Renamed ER_INCO_SUBDEVICE_UNKNOWN to ER_INCO_DEVICE_UNKNOWN
                         and added ER_INCO_SUBDEVICE_UNKNOWN with a new error-number
3.03.02 25.10.2004-RZ: + Due to the change of the version system, GetRevisions
                         has been changed too.
3.03.03 01.11.2004-RZ: ! Fixed 2 memory leaks in ProcessIncoFrame()
3.03.04 15.11.2004-RZ: ! Changed char* to const char*.
3.03.04 16.11.2004-RZ: ! PutVariable() and GetVariable() do now check the 
                         Lenght-argument. Before the inco32.dll crashed if 
                         those values were greater than 256 (which is the
                         maximum amount of bytes the incoserver/inco32 3.x 
                         supports. If the Length arg ist to high now, an
                         ER_INCO_VAR_STRING_LENGTH error is returned by 
                         PutVariable. GetVariable tries to perform the 
                         INCOCall with the Maximum size (256) and if this
                         is enough, it doesn't return an error, otherwise
                         it does also return ER_INCO_VAR_STRING_LENGTH.
3.03.05 04.01.2004-RZ: ! DbgTasksState, DbgTasksList: didn't return an error
                         If the given buffer was too small (instead they 
                         returned the amount of information fitting into
                         the buffer - but didn't complain about the to small
                         buffer. Now they behave like in the 2.x INCOServer.
3.04.00 17.01.2005-RZ: ! The size of data has changed to 464 (from 256) in
                         the libindel/defsw.h. Put/GetBlocks do still use
                         256 bytes as max data size - because of 2 resons:
                         1. The incoserver does use an array on stack with 
                            256 Bytes for Put/GetBlocks from/to the DPR of 
                            a PPC.
                         2. The ACSr-6A does only have such a small buffer
                            and would crash if we make PutBlocks greater
                            than 256*2 (e.g. trans32 does that).
3.04.01 25.01.2005-RZ: ! There are new XML config entries which allows the
                         user to configure the maximum length of Put-/Get-
                         Block's. Therefore a new List has been invented to 
                         hold those setting (called CTargetOverride).
                       ! PutBlock/GetBlock-max default-length has been 
                         increased to 464 Bytes again - because now the size 
                         is adjustable by the configurtin xml file (see above)
3.04.04 24.02.2005-MS: ! Added #define for "Template" and "Edit" state.
3.05.00 05.04.2005-RZ: ! PutBlock, GetBlock fixed wrong error code when data
                         length where 0. Before an undefined error number was
                         returned.
                       + Added functions and calls, so that CallProcedure,
                         PutVariable and GetVariable will recognise if an 
                         INCO call has the target of the "own" process - and
                         does therefore not send the frame to the server.
3.05.01 20.04.2005-RZ: ! Fixed small bug in GetRevisions which affects only 
                         person who are working with the INIXServer. Concrete:
                         GetRevisions failed if performed with the dll not 
                         matching the server (e.g. faile when inco_32.dll 
                         accessed an INIXServer or vice versa).
3.05.02 16.05.2005-RZ: ! Fixed crash that happened if a call was made to 
                         target '.' and 0 dispatchers were registered.

713, 2006-05-29 11:00:32 +0200 (Mo, 29 Mai 2006), fabi
+ New error codes ER_INCO_DBG_NO_DEVICE and ER_INCO_DBG_NO_SOFT_RESET.

762, 2006-07-26 15:04:55 +0200 (Mi, 26 Jul 2006), fabi
+ Added ULL makros for unsigned long long constants.

838, 2006-08-15 09:12:36 +0200 (Di, 15 Aug 2006), fabi
! Fixed InternLog definition if logging is disabled.

974, 2006-09-18 15:51:52 +0200 (Mo, 18 Sep 2006), walther
+ Copied ISMGetBlockXX() etc. functions from Ism_inco_32.dll
  (https://indel.dyndns.org/private/sw/old/trunk/inco/Ism_inco_32/Ism_inco_32.cpp
  r68) into libinix32, with small changes to remove Windows dependencies.
  These functions are used in the memdump plugin, which can't use
  Ism_inco_32.dll because of conflicts between libinix32 and inco_32.dll.

975, 2006-09-19 08:30:58 +0200 (Di, 19 Sep 2006), walther
! Changed Slave argument of ISM functions from char * to const char *.

1043, 2006-11-08 16:59:12 +0100 (Mi, 08 Nov 2006), walther
+ Added a ticket system to allow synchronous calls of asynchronous
  procedures within INIX (see documentation in inix32.h).

1130, 2006-12-11 10:46:06 +0100 (Mo, 11 Dez 2006), walther
+ Added a facility for asynchronous procedures to return result values.

1149, 2006-12-12 08:42:24 +0100 (Di, 12 Dez 2006), zulliger
! Minor error code cleanups. No functional changes.

1199, 2007-01-10 07:38:50 +0100 (Mi, 10 Jan 2007), zulliger
+ New errorcode "Async result lost"

1223, 2007-01-22 14:19:42 +0100 (Mo, 22 Jan 2007), walther
! Some documentation clarifications.
- Removed unnecessary GetVariableSync() function (GetVariable() is already
  synchronous).

1326, 2007-02-27 14:55:39 +0100 (Di, 27 Feb 2007), fabi
+ New errors ER_INCO_RPC_MULTIDISPATCH, ER_INCO_RPC_ARG_FORMAT.

1492, 2007-03-30 15:08:21 +0200 (Fr, 30 Mrz 2007), zulliger
- Removed Get/PutVariableBlock functions. INIXServer 3.x apps are not 
  allowed to use those functions anymore.

1664, 2007-06-27 17:17:59 +0200 (Wed, 27 Jun 2007), walther
! Fixed some more messed up changelogs.

1716, 2007-07-06 17:31:52 +0200 (Fr, 06 Jul 2007), walther
+ Added LL macro for int64 constants.

2324, 2007-12-18 11:09:33 +0100 (Di, 18 Dez 2007), zulliger
! Set svn:keywords (why were these lost?).

2370, 2007-12-20 10:09:47 +0100 (Do, 20 Dez 2007), zulliger
- Removed ISM function defintions from header. Users of ISM functionality 
  must include the ism_inco_32.h file.

2398, 2007-12-24 16:07:03 +0100 (Mo, 24 Dez 2007), zulliger
+ Readded GetServerRevisionS
! Better const correctness

2428, 2008-01-04 11:28:45 +0100 (Fr, 04 Jan 2008), zulliger
! If neither INDEL_WINDOWS nor INDEL_LINUX are defined, we assume 
  INDEL_WINDOWS by default. This helps to be backward compatible with old
  inco_32.h files.

2434, 2008-01-09 08:07:19 +0100 (Wed, 09 Jan 2008), zulliger
+ Additional functions moved over from inix32.h

2440, 2008-01-09 16:30:33 +0100 (Mi, 09 Jan 2008), zulliger
+ Added define when compiled on Linux

2518, 2008-02-07 14:38:59 +0100 (Thu, 07 Feb 2008), zulliger
+ If INCO32_EXPORT is already defined, do not change its definition. Was
  introduced for incoserver, where the define is set to nothing (neither
  dll import, nor dll export)

2546, 2008-02-08 13:25:34 +0100 (Fri, 08 Feb 2008), walther
! Fixed compile issue on Linux boxes

2618, 2008-02-27 15:46:42 +0100 (Wed, 27 Feb 2008), walther
! Set svn:eol-style property where appropriate and svn:ignore a generated
  file. [25 files]

2629, 2008-02-29 15:30:15 +0100 (Fr, 29 Feb 2008), walther
! Just noticed that I made a bit of a mess in the changelogs in r2618. Not
  sure what happened - cleaning this up...

3894, 2010-01-14 16:05:50 +0100 (Do, 14 Jan 2010), walther
+ Support for asynchronous calls to external targets. The API functions
  taking asynchronous call tickets now also take a target name to
  disambiguate the tickets. This breaks binary compatibility for
  applications that use these functions (only INIX to my knowledge), hence
  the version number bump by tagging the previous revision. Ticket
  machineries now exist one per target, the one for target "." is special
  in that it also generates tickets (handles both the caller and the target
  side of asynchronous calls), while the others only manage foreign tickets
  (only handle the caller side). There is no support for handling incoming
  asynchronous calls from the server yet. Documentation is not updated yet.

3962, 2010-02-08 15:06:25 +0100 (Mo, 08 Feb 2010), walther
+ Added function WaitForAsyncCallWithTimeout, like WaitForAsyncCallToFinish
  but with timeout.

3965, 2010-02-09 09:05:09 +0100 (Di, 09 Feb 2010), walther
! Updated documentation for the recent API changes.

3994, 2010-02-23 10:20:37 +0100 (Di, 23 Feb 2010), fabi
! Adjusted to generate java classes with swig.

3999, 2010-02-25 16:41:54 +0100 (Do, 25 Feb 2010), fabi
! Exclude the 3.0 functions when generating the java interface as they are
  not needed and pollute the interface.

4186, 2010-06-10 16:37:37 +0200 (Do, 10 Jun 2010), zulliger
+ Added include required for the INCO-types (indeldefs.h)
+ Added include useful for customers to check for error returned by INCO
  functions (errinco.h)

4208, 2010-06-15 13:41:21 +0200 (Di, 15 Jun 2010), zulliger
+ Added API documentation for CallProcedureEx & friends. No interface 
  changes

4212, 2010-06-15 16:00:43 +0200 (Tue, 15 Jun 2010), walther
+ Added ProcedureExAddResult and ProcedureExAddAppError functions to
  complete the new asynchronous procedure API.
- Removed the previous asynchronous procedure API superseded by the
  CallProcedureEx* functions, since due to the change in CallProcedure there
  was no way to keep it backwards compatible.

4227, 2010-06-16 09:05:18 +0200 (Mi, 16 Jun 2010), walther
! Fixed Linux build ("error: 'NULL' was not declared in this scope").

4228, 2010-06-16 16:56:42 +0200 (Mi, 16 Jun 2010), walther
! Updated documentation for the added and removed functions from r4212 and
  4214, and a lot of other small documentation tweaks.

4248, 2010-06-24 11:38:29 +0200 (Do, 24 Jun 2010), walther
! When a procedure that normally returns named results returns an
  application error instead, the first attempt to get a result by name now
  returns that application error instead of ER_INCO_RPC_UNKNOWN_TICKET, just
  like the first attempt to get an unnamed result would.
! It is now supported for both process-internal and inter-process calls to
  return additional results after an application error (e.g. details about
  the error). To enable consistent behavior among process-internal calls,
  inter-process calls to inco_32 processes, and calls to INOS, it is now
  specified that there may be at most one application error and it must come
  before any other results. ProcedureExAddAppError() will now wipe out any
  previously set results and app errors to enforce this.

4481, 2010-08-11 15:27:59 +0200 (Mi, 11 Aug 2010), walther
+ Handle error ER_INCO_RPC_INTERRUPTED that occurs when the INCOServer
  detects a target reset while an asynchronous procedure is in progress.
  Caveat: CallProcedureExWait() returns ER_INCO_NO_ERROR in such a
  situation, ER_INCO_RPC_INTERRUPTED is only returned from
  CallProcedureExResult(). This was simpler to implement and seems
  sufficient for now.

4578, 2010-10-08 14:36:44 +0200 (Fri, 08 Oct 2010), fabi
! Removed INDEL_JAVA def check to include everything in the java binding.

4700, 2010-12-03 17:14:06 +0100 (Fr, 03 Dez 2010), zulliger
! Adjusted Eclipse projects

4770, 2011-02-17 14:23:07 +0100 (Do, 17 Feb 2011), zulliger
+ Added new interface functions: DbgEmeCommStatus and DbgOsContinue.

4914, 2011-06-14 09:33:59 +0200 (Di, 14 Jun 2011), zulliger
! Reworked inco_32.h in order to have better doxygen documentation. Thereby
  adjusted argument names, ordering of functions, documentation itself,
  etc. Other than documentation, nothing should have changed.

4969, 2011-09-02 17:31:38 +0200 (Fri, 02 Sep 2011), walther
! Clarify documentation regarding ER_INCO_RPC_NO_RETURN_VALUE and
  ER_INCO_RPC_UNKNOWN_TICKET.

4984, 2011-10-04 14:09:50 +0200 (Di, 04 Okt 2011), zulliger
+ Added support for new Dbg INCO command: DbgTaskGetReg. This command has
  initially been introduced to support getting registers from P2020. At the
  same time, the command has been designed to optimize getting taks
  specific registers for all targets, in the way GDB requires them.
  Therefore, this new command will help minimizing communication overhead
  when debugging with Gdb/iDev.

4996, 2011-10-21 15:30:28 +0200 (Fr, 21 Okt 2011), walther
+ Add a new interface function IncoControl() that provides a generic way of
  querying and manipulating miscellaneous library state or settings. Its
  one currently implemented function permits setting the address of the
  INCOServer to connect to when using TCP.

4997, 2011-10-21 16:09:33 +0200 (Fr, 21 Okt 2011), walther
+ Port libinco_32 to Mac OS X and iOS. Only TCP communication is supported
  at this time. Building for Mac OS X works using ibuild.py like on Linux.
  For iOS, an Xcode project is provided. It requires wxWidgets-2.9.2
  (unmodified source distribution), placed relative to the project as
  specified by the WXROOT build setting.

5174, 2012-05-10 15:23:55 +0200 (Do, 10 Mai 2012), walther
! Don't use __declspec(dllexport) in addition to specifying exported
  symbols in libinco_32.def, as doing both results in warnings from the
  Microsoft x64 linker. See http://support.microsoft.com/kb/835326/.
  Removing it makes no difference in the produced binary.

5218, 2012-06-07 18:28:02 +0200 (Do, 07 Jun 2012), zulliger
+ Added data transfer feature. "Data transfers" serves two major purposes:
  The first is to send huge amount of data from PC to target and vice versa
  by getting the most out from the transfer technology (e.g. use 1500 byte
  for each ethernet frame) and second do this "directly" (i.e. not by using
  the INCOServer process).

5354, 2012-10-29 09:07:05 +0100 (Mon, 29 Oct 2012), walther
! Fix some mistakes and omissions from when syntax documentation was copied
  from inixdev/doc/user/syntax.dox (r4914).

5386, 2012-11-19 15:05:26 +0100 (Mon, 19 Nov 2012), zulliger
+ Added support for watchpoints

5497, 2013-02-07 15:35:38 +0100 (Thu, 07 Feb 2013), tjericke
+ Added DTClose and DTGetBufferSizes functions.
! Made DataChannels (DT) available for pure C.

5556, 2013-03-20 14:33:17 +0100 (Wed, 20 Mar 2013), pauli
! Fixed documentation: Renamed INCO_ERROR_NO_ERROR to ER_INCO_NO_ERROR.

5703, 2013-06-18 09:19:36 +0200 (Di, 18 Jun 2013), zulliger
+ Added new INCO functions: DbgTaskRangeStep, DbgTargetGetDataMulti,
  DbgTaskGetDataMulti, DbgTaskGetDataFromCache to speed up debugging with
  iDev.

5740, 2013-07-22 08:45:29 +0200 (Mon, 22 Jul 2013), walther
! Fix syntax error that confused JNAerator.

5773, 2013-09-23 17:37:29 +0200 (Mon, 23. Sep 2013), zulliger
+ Added new INCO function: DbgTaskPutGdbReg. It has initially been
  introduced to support new ARM CPUs. This function passes the register
  setting string, produced by GDB, down to the INOS. Those string look like
  "40=00001580" where the "40" is the register number and the rest is the
  hex encoded register value. This function has been added to simplify the
  gdb stub so that it does not need to know which register is meant by
  "40".

5960, 2014-02-19 10:37:05 +0100 (Mi, 19 Feb 2014), zulliger
+ Added new API call: GetMessage. This function can be used to resolve an
  error code (e.g. received by CallProcedureExSync) to a McRobot message.
! Fixed compiler warnings when including this header in a .c file using
  a C-compiler (had to add 'void' to function with empty argument list)

5971, 2014-02-20 08:42:09 +0100 (Do, 20 Feb 2014), zulliger
! Fixed C-function name conflict: GetMessage is part of the Windows C-API.
  Therefore, renamed GetMessage into GetMcMessage

5978, 2014-02-24 16:01:16 +0100 (Mo, 24 Feb 2014), pauli
+ Added comment stating Data Transfer usage rule to avoid deadlocks 
  when dealing with unreliable channels.

5989, 2014-03-03 10:42:42 +0100 (Mo, 03 Mrz 2014), pauli
! DT documentation review by zulliger.

6181, 2014-08-06 17:05:08 +0200 (Wed, 06 Aug 2014), pauli
+ Added new INIX frame dispatching functions (Indel internal use):
  Register-/UnregisterAdditionalDispatcherByThread. These functions allow
  to register a INCO frame handler specific to the calling thread so that
  multiple top-level dispatchers ("") can exist per process. This
  functionality is required by the INIX mapwatch plugin which needs to
  register a dispatcher per crash target besides the dispatcher for the
  INIX application.

6534, 2015-11-12 00:51:52 +0100 (Don, 12 Nov 2015), zulliger
! Slightly doxygen doc (no functional changes). Namely: explicitly mention
  that CallProcedureExWait does NOT return application errors and that
  CallProcedureExResult has to be used for that.

6539, 2015-12-11 09:54:24 +0100 (Fr, 11 Dez 2015), pauli
+ Added INCO recording feature. It can be used to log INCO calls to a file
  for analysis. The file contains timing information, so the calls can be
  replayed to e.g. simulate an HMI. The recorder can be started/stopped via
  the IncoControl call using commands IncoCtlStartRecorder and
  IncoCtlStopRecorder. Currently, only CallProcedures and data transfers
  are recorded.

6633, 2016-06-17 09:34:39 +0200 (Fri, 17 Jun 2016), zulliger
! Slightly clarified the handling of the 'timeout' parameter of DTRecive.
  No functional changes.

7327, 2020-04-09 13:56:47Z, pauli
! INCO Lite: Fixed too large frame size for retries, fixed alignment of
  CallProcedureEx frames (was bad when the frame number was escaped in the
  header).

7328, 2020-04-14 06:56:50Z, pauli
! Fixed common build.

7332, 2020-04-16 09:08:02Z, pauli
! Changed include indel/incotypes.h to inco_32/incotypes.h

7466, 2020-09-15 15:45:17Z, walther
! Use symbol visibilitiy to avoid exposing library internals on Linux. 
  Only explicitly export functions that are part of the public API. This
  avoids symbol clashes and accidental use of internals. In order to avoid
  having another file similar to libinco_32.def to maintain, I chose to use
  visibility attributes rather than the libtool -export-symbols option (as
  done for INIX plugins).  Originally an attempt to fix the problem from
  libindel r7465, which it does not (visibility of symbols coming from a
  static library is set there, not here), but it's a good thing anyway. 
  Unit tests that access internals can no longer do that through the shared
  library API but need to compile/link the respective files themselves,
  same as already done on Windows.

7514, 2020-10-30 15:31:39Z, pauli
! Added support for receiving async results from a different thread than
  the one that called CallProcedureEx (aka Ticket Delegation). Feature has
  to be explicitly enabled by calling IncoControl() with
  IncoCtlAllowTicketDelegation. Internally, this is done by using a single
  ticket machinery instance per target for all threads. CallProcedureExWait
  now uses the same communication channel than the thread that created the
  ticket, meaning that a CThreadCommData object is now shared between
  threads. Synchronization is done over the newly introduced critical
  section CThreadCommData::m_Lock together with a hopefully-not-too-smart
  pointer TLockedThreadCommData.

7551, 2020-11-25 15:18:12Z, hirzel
+ Introduced support for PutGetBlockEx.. INCO functions.

7760, 2021-10-01 14:23:08Z, fabi
+ Implemented inco call TgtCharacteristics to not rely only on
  GetVariable("Target.Characteristics").

7808, 2022-01-19 14:33:16Z, fabi
+ Fixed #2850: Added DbgTasksListEx, DbgTaskGetNameEx and DbgTaskGetDataEx
  functions.

7810, 2022-01-20 06:48:14Z, pauli
! Fixed build for stone age MSVC++ 6.0 compiler still used by some
  customer: Due to a bug, it does not support partial template
  specialization, see https://stackoverflow.com/a/67898643/5464232 (since
  r7327)

7812, 2022-01-20 07:55:04Z, pauli
! Fixed version check for non-MSVC compilers (since r7810, credits to cw).

7830, 2022-02-21 15:33:47Z, hirzel
+ Added extended 64 bit debug functions
  DbgTasksStateEx,DbgTaskGetIdEx,DbgTaskSetBreakpointEx,DbgTaskClrBreakpointEx,DbgTaskGtBreakpointEx,DbgTaskHaltEx,DbgTaskRunEx,DbgTaskSingleStepEx,DbgTaskRangeStepEx.

7845, 2022-03-03 08:43:42Z, hirzel
+ Added various Dbg...Ex methods to fully support 64 bit target debugging.

7864, 2022-03-04 14:14:00Z, hirzel
! Cookies of DbgxxxEx functions have to be uint64 on 64 bit targets.

8343, 2023-08-31 13:19:13Z, walther
! Fix assertion failure and potentially mangled task information when
  debugging a 64-bit target. These targets send TaskDataMulti frames
  containing 64-bit cookies, which need to be parsed and passed along
  differently than the traditional 32-bit ones. This is an API change for
  DbgTaskGetDataFromCacheEx, but since nobody except sgdbstub is expected
  to use this obscure function, the risk is contained. An old sgdbstub
  calling a new libinco_32 might crash or misbehave.

8350, 2023-09-26 12:52:43Z, hirzel
+ Added missing 64 bit debug function DbgTaskPutGdbRegEx.

8456, 2024-02-15 10:27:22Z, fabi
+ Add support for getting extended target characteristics (with max sizes etc).

$LastChangedRevision$ $iDate$ $Author$
! Leave out default value in TgtCharacteristicsEx as with 0 we just get the
  same value as TgtCharacteristics.

$Comment$

u = unreleased
+ = new feature
! = change, bugfix
- = removed

Remarks

project         : Inco32 Version 3
language        : C++ (Gnu, Visual C++)
system          : Linux, Windows

All dll/so function provided by this project (the interface) are defined and implemented here.

Enumeration Type Documentation

enum DTCtlRequest

Request identifiers for IncoControl().

Enumerator
DTCtlForceConnect	! e.g. DTControl("SUT", DTCtlForceConnect, "DataTransfer.Endpoints.TestUtilEndpoint", strlen("DataTransfer.Endpoints.TestUtilEndpoint")+1);

enum IncoCtlRequest

Request identifiers for IncoControl().

Enumerator
IncoCtlSetTcpServerAddress	Set the IP address or hostname of the INCOServer when TCP communication is used. Arguments: TargetPath: ignored apData: const char *; pointer to a null-terminated string, or NULL auDataLength: ignored Return value: always ER_INCO_NO_ERROR Changing the server address affects all INCO calls done afterwards from any thread. Be careful when changing the address after doing asynchronous INCO calls: disconnecting from the server will make it impossible to receive their completion notification or results, and waiting for them afterwards may block forever. The default server address before calling this for the first time or after calling it with a NULL or empty string argument is 127.0.0.1. This request always succeeds as it only stores the passed value. The connection to the server is only opened at the first subsequent INCO call using TCP, and any errors in address resolution or connection to the server will be reported at that time by returning an appropriate error code (e.g. ER_TARGET_REMOTE_SRV_NOT_FOUND).
IncoCtlStartRecorder	Start recording INCO calls into a file for later replay. Arguments: TargetPath: ignored apData: const char *; output file path auDataLength: ignored Return value: ER_INCO_NO_ERROR on success
IncoCtlStopRecorder	Stops the current recording of INCO calls. Arguments: TargetPath: ignored apData: ignored auDataLength: ignored Return value: always ER_INCO_NO_ERROR
IncoCtlAllowTicketDelegation	Allow waiting for async results from other threads than the one that originally obtained the ticket. Arguments: TargetPath: ignored apData: uint32*; 0 = Disallow (default), 1 = Allow auDataLength: sizeof(uint32) Return value: ER_INCO_NO_ERROR on success Setting this flag allows scenarios where one or multiple threads uses CallProcedureEx to get a ticket, and then delegate the task of waiting for the async result using CallProcedureExWait/Result to other threads (producer/consumer pattern). Note that there may still be only one thread calling CallProcedureExWait/Result for a given ticket at the same time.

Function Documentation

INCO32_EXPORT int32 WINAPI CheckoutAsyncCallTicket

(

void

)

Called by an asynchronous procedure when an asynchronous action starts.

During its synchronous part, a procedure calls this function to tell libinco_32 that it is about to start an asynchronous part. It must make sure that the returned ticket is eventually returned to libinco_32 using ReturnAsyncCallTicket() (when the asynchronous part finishes) or ReturnAsyncCallTicketAfterCallHasFinished(). May be called multiple times, but each one must be balanced by a call to ReturnAsyncCallTicket() or ReturnAsyncCallTicketAfterCallHasFinished().

See also Details in Synchronous Calling of Asynchronous Procedures

INCO32_EXPORT uint32 WINAPI DbgClrWatchpoint	(	const char *	TargetPath,
		uint32	auAddress
	)

Clears the watchpoint at address auAddress.

Parameters

auAddress

The address of the watchpoint that should be cleared. The address must be within the watched range. Means: it doesn't necessarily need to be the same value as returned by DbgSetWatchpoint (apAddress), as long as the address lies within the watched memory region.

Note

As of this writing, all INOS targets only support 1 watchpoint. These implementation do not even check auAddress. Instead, they always just remove the watchpoint if one is set.

INCO32_EXPORT uint32 WINAPI DbgClrWatchpointEx	(	const char *	TargetPath,
		uint64	auAddress
	)

ClrWatchpoint on 64bit systems, otherwise like DbgClrWatchpoint.

INCO32_EXPORT uint32 WINAPI DbgEmeCommStatus	(	const char *	TargetPath,
		uint32 *	apEmeCommStatus
	)

Get status about 'emergency INCO communication' of target TargetPath. Value at apEmeCommStatus will be set to 0 if the emergency system is not running. It'll be set to 1 if it is running.

INCO32_EXPORT uint32 WINAPI DbgOsContinue	(	const char *	TargetPath,
		uint32	auFlags
	)

Continue execution of OS. If auFlags is 0 and the 'emergency INCO communication' is running, this emergency communication will be left and "normal" OS execution will be continued.

INCO32_EXPORT uint32 WINAPI DbgSetWatchpoint	(	const char *	TargetPath,
		uint32	auAddress,
		uint32	auSize,
		uint32	auFlags,
		uint32 *	apAddress,
		uint32 *	apSize
	)

Set a watchpoint on address auAddress with auAddress and auFlags.

Parameters

auAddress	The desired address of the watchpoint.
auSize	The desired size of the watchpoint
auFlags	1: read acces, 2: write access, 3: read & write access
apAddress	The effective watchpoint address, which may differ from auAddress because certain CPU have certain watchpoint constraints (such as the IBM 750, which may only cover addresses which are 8Byte aligned).
auSize	The effetive watchpoint size, which may differ from auSize because certain CPU have certain watchpoint constraints (such as the IBM 750, which may only cover 8Bytes of data).

INCO32_EXPORT uint32 WINAPI DbgSetWatchpointEx	(	const char *	TargetPath,
		uint64	auAddress,
		uint64	auSize,
		uint32	auFlags
	)

SetWatchpoint on 64bit systems, otherwise like DbgSetWatchpoint.

INCO32_EXPORT uint32 WINAPI DbgTargetGetDataMulti	(	const char *	TargetPath,
		uint32 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

Get all kind of target specific data, such as: task list, their state and tbentries, breakpoint/watchpoint/testpoint list, etc. The caller decides which data to be read by *apFlags. INOS reports which data were actually sent back by *apFlags. Each version of INOS may support different kind of data. Therefore, check the INOS sources for a list of supported flags. If the data don't fit into a single INCO ACK frame, then *apCookie will be set to !=0, apRemainingDataLength will be set to the count of bytes of additionally available data. The caller can invoke this function again, passing *apCookie to get the remainig data. may pass that cookie to the next

INCO32_EXPORT uint32 WINAPI DbgTargetGetDataMultiEx	(	const char *	TargetPath,
		uint64 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

TargetGetDataMulti on 64bit systems, otherwise like DbgTargetGetDataMulti.

INCO32_EXPORT uint32 WINAPI DbgTaskClrBreakpointEx	(	const char *	TargetPath,
		const char *	aTaskName,
		uint64	aAddress
	)

Clear breakpoint on 64bit systems, otherwise like DbgTaskClrBreakpoint.

INCO32_EXPORT uint32 WINAPI DbgTaskGetBreakpointEx	(	const char *	TargetPath,
		uint32	aNumber,
		void *	aResult,
		uint32	aLength
	)

Get breakpoint on 64bit systems, otherwise like DbgTaskGetBreakpoint.

INCO32_EXPORT uint32 WINAPI DbgTaskGetDataEx	(	const char *	TargetPath,
		uint64	aTaskId,
		uint32	aDataDef,
		void *	aResult,
		uint32	aLength
	)

Get extended task data on 64bit systems, otherwise like DbgTaskGetData.

INCO32_EXPORT uint32 WINAPI DbgTaskGetDataFromCache	(	const char *	TargetPath,
		uint32 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

For certain INCO calls (i.e. SingleStep, RangeStep, Halt), new INOS versions return task state data in the ACK frame to optimize the amount of frames to be exchanged between the PC and INOS during debugging. These data are stored within libinco_32 and can be get by this function. The format of the data and the way to get possibly "remaining data" is the same as for DbgTargetGetDataMulti.

INCO32_EXPORT uint32 WINAPI DbgTaskGetDataFromCacheEx	(	const char *	TargetPath,
		uint64 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

TaskGetDataFromCache on 64bit systems, otherwise like DbgTaskGetDataFromCache.

INCO32_EXPORT uint32 WINAPI DbgTaskGetDataMulti	(	const char *	TargetPath,
		uint32	aTaskId,
		uint32 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

Get all kind of task specific data, such as: task state, trap number, registers values, tb entries, etc. This function works the same way as DbgTargetGetDataMulti.

INCO32_EXPORT uint32 WINAPI DbgTaskGetDataMultiEx	(	const char *	TargetPath,
		uint64	aTaskId,
		uint64 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength,
		uint32 *	apRemainingDataLength
	)

TaskGetDataMulti on 64bit systems, otherwise like DbgTaskGetDataMulti.

INCO32_EXPORT uint32 WINAPI DbgTaskGetIdEx	(	const char *	TargetPath,
		const char *	aTaskName,
		uint64 *	aTaskId
	)

Get extended task id on 64bit systems, otherwise like DbgTaskId.

INCO32_EXPORT uint32 WINAPI DbgTaskGetNameEx	(	const char *	TargetPath,
		uint64	aTaskId,
		char *	aTaskName,
		uint32	aLength
	)

Get extended task name on 64bit systems, otherwise like DbgTaskGetName.

INCO32_EXPORT uint32 WINAPI DbgTaskGetReg	(	const char *	TargetPath,
		uint32	aTaskId,
		uint32 *	apCookie,
		uint32 *	apFlags,
		void *	apBuffer,
		uint32 *	apBufferLength
	)

Deprecated:

This function has been replaced by the more powerful DbgTaskGetDataMulti.

INCO32_EXPORT uint32 WINAPI DbgTaskHaltEx	(	const char *	TargetPath,
		uint64	aTaskId
	)

Halt task on 64bit systems, otherwise like DbgTaskHalt.

INCO32_EXPORT uint32 WINAPI DbgTaskPutGdbReg	(	const char *	TargetPath,
		uint32	aTaskId,
		const uint32	auRegister,
		const void *	apData,
		uint32	auDataLength
	)

Set a register at the target in 'GDB style' syntax. This syntax is defined by GDB's serial remote protocol and looks like this: "RegNum=RegValue" So for example, to set the value of the PC on a PPC603, you'd have a string like that: "40=deadbeef" Initially, this function has been introduced to support targets with ARM CPUs (i.e. COP-MAS2). Thereby, we adjusted the GDB stub so that it doesn't need to know anything about register numbers anymore (means: doesn't need to know that register number 40 is the PC). Thereby, we moved that know how to INOS, thus this new function.

INCO32_EXPORT uint32 WINAPI DbgTaskPutGdbRegEx	(	const char *	TargetPath,
		uint64	aTaskId,
		const uint32	auRegister,
		const void *	apData,
		uint32	auDataLength
	)

TaskPutGdbReg on 64bit systems, otherwise like DbgTaskPutGdbReg.

INCO32_EXPORT uint32 WINAPI DbgTaskRangeStep	(	const char *	TargetPath,
		uint32	aTaskId,
		uint32	auFrom,
		uint32	auTo
	)

Performs at least one task single-steps. Performs more task single-steps as long as the task PC is >= auFrom and < auTo. This function is a pure debug performance optimization, as the same functionality can be get by issuing several DbgTaskSingleStep from the PC side.

INCO32_EXPORT uint32 WINAPI DbgTaskRangeStepEx	(	const char *	TargetPath,
		uint64	aTaskId,
		uint64	auFrom,
		uint64	auTo
	)

Rangestep task on 64bit systems, otherwise like DbgTaskRangeStep.

INCO32_EXPORT uint32 WINAPI DbgTaskRunEx	(	const char *	TargetPath,
		uint64	aTaskId
	)

Run task on 64bit systems, otherwise like DbgTaskRun.

INCO32_EXPORT uint32 WINAPI DbgTaskSetBreakpointEx	(	const char *	TargetPath,
		const char *	aTaskName,
		uint64	aAddress
	)

Set breakpoint on 64bit systems, otherwise like DbgTaskSetBreakpoint.

INCO32_EXPORT uint32 WINAPI DbgTaskSingleStepEx	(	const char *	TargetPath,
		uint64	aTaskId
	)

Singlestep task on 64bit systems, otherwise like DbgTaskSingleStep.

INCO32_EXPORT uint32 WINAPI DbgTasksListEx	(	const char *	TargetPath,
		void *	aResult,
		uint32	aLength
	)

Get extended task list on 64bit systems, otherwise like DbgTasksList.

INCO32_EXPORT uint32 WINAPI DbgTasksStateEx	(	const char *	TargetPath,
		void *	aResult,
		uint32	aLength
	)

Get extended task states on 64bit systems, otherwise like DbgTasksState.

INCO32_EXPORT void WINAPI DTClose

(

tLDTFileDescriptor

FileDescriptor

)

Closes a data transfer connection

Parameters

FileDescriptor

The file descriptor that was set by DTOpen

INCO32_EXPORT uint32 WINAPI DTOpen	(	const char *	TargetPath,
		const char *	Endpoint,
		tLDTFileDescriptor *	FileDescriptor
	)

Opens a data transfer. This function tries to establish a connection to the endpoint on the target.

Parameters

TargetPath	Definition of the TargetPath
Endpoint	A zero-terminated string of the INCO path of the endpoint to which the connection should be established
FileDescriptor	Pointer to a tLDTFileDescriptor. If the function succeeds, the file descriptor will be set to a valid value that must be passed to every call of DTClose, DTSend and DTReceive

Returns

ER_INCO_NO_ERROR on success.

ER_INCO_DT_ALREADY_CONNECTED if the target reports that a connection is already established. If it is desired t re-establish the connection, the DTControl can be called using DTCtlForceConnect followed by another attempt to DTOpen.

A request-specific error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI DTReceive	(	tLDTFileDescriptor	FileDescriptor,
		void *	DataBuffer,
		uint32	DataBufferSize,
		uint32 *	DataLength,
		int32	TimeoutMs
	)

Parameters

FileDescriptor	The file descriptor that was set by DTOpen
DataBuffer	Pointer to the buffer where this function puts received data into
DataBufferSize	Buffer size in bytes. The buffer size must be big enough to take the maximum configured data transfer size as specified by the target.
DataLength	Output parameter that'll contain the number of received bytes.
TimeoutMs	Maximum time to wait for a data transfer to start. Moreover, if a data transfer is big enough so that it requires multiple "sub-data transfers" (i.e. multiple UDP frames) then the timeout is also used to wait for every sub-data transfer. Therefore: If sub-data transfers are required, the overall time spent in this function may be significantly higher than TimeoutMs. More technically spoken: This timeout is used for each attempt of reading one UDP/Ethernet frame. This also implies that, assuming you transfer 15'000 Bytes (= 10 Ethernet frames in case of a DataTransfer), the underlying code needs 10 times to read a UDP frame and thus the timeout is applied on every read attempt. Therefore, if only one of these 10 frames would not arrive within TimeoutMs, the whole transfer would be aborted with a timeout error, whether some frames were received successfully or not. The very same holds true for transfer technologies other than UDP, just that the 'frame sizes' are different from 1500 Bytes.

Returns

ER_INCO_NO_ERROR on success.

A request-specific error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI DTSend	(	tLDTFileDescriptor	FileDescriptor,
		const void *	DataBuffer,
		uint32	DataLength
	)

Sends the data pointed to by DataBuffer to the target. This function returns when sending the data completed or failed. The function applies the timeout and retry properties as defined by the target. Therefore, the execution time of this function may significantly increase in case of transfer problems (e.g. UDP frame loss, etc.)

Parameters

DataBuffer	Pointer to the data that should be sent to the target
DataLength	Count of Bytes sent to the target.
FileDescriptor	The file descriptor that was set by DTOpen

Returns

ER_INCO_NO_ERROR on success.

A request-specific error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetServerRevisionS

(

uint8 *

aServerVersion

)

Function to get the INCOServer revision.

Deprecated:

INCO32_EXPORT uint32 WINAPI IncoControl	(	const char *	TargetPath,
		int32	aiRequest,
		void *	apData,
		uint32	auDataLength
	)

Query and manipulate miscellaneous internal library state and settings.

Parameters

TargetPath	if aiRequest is target-specific, specifies the target (Definition of the TargetPath). Ignored for non-target-specific requests.
aiRequest	a constant from enum IncoCtlRequest, determines the action to be performed.
apData	pointer to request-specific input and output parameters.
auDataLength	size of the structure or buffer pointed to by apData, request-specific.

Returns

ER_INCO_NO_ERROR on success.

ER_INCO_CTL_UNKNOWN_REQUEST if aiRequest is invalid.

A request-specific error code from <inco_32/errinco.h> (see Error returned by INCO functions).

See documentation of individual actions in IncoCtlRequest for information about use and meaning of TargetPath, apData, auDataLength, and possible return values.

INCO32_EXPORT int32 WINAPI PopDeferredCallTicket

(

void

)

Called by a deferred CallProcedure handler to remove a ticket from libinco_32's stack.

This function is used in the inner workings of Synchronous Calling of Asynchronous Procedures and is not of general interest. See CDeferredProcedureCallData::Perform() in libinix for an example of its use.

INCO32_EXPORT uint32 WINAPI ProcedureExAddAppError	(	int32	Ticket,
		uint32	auAppError
	)

Called by an asynchronous procedure to return an application error.

When an asynchronous part of a procedure wants to return an application error (see Application errors: McRobot, INIX and customer code), it calls this function before calling ReturnAsyncCallTicket(). Application errors differ from ordinary result values (as set by ProcedureExAddResult()) in that they are retrieved as the return value of CallProcedureExResult() rather that through its pointer arguments. For a given ticket, there is at most one application error and it always comes before any other results. Calling this function will wipe out any results previously added using ProcedureExAddResult() and replace any previously set application error. You can, however, add more results after setting the application error, e.g. to give details about the error.

Parameters

Ticket	The ticket that the synchronous part of the procedure got from CheckoutAsyncCallTicket().
auAppError	The error code to be set. Should be in the range reserved for application errors, as defined in Application errors: McRobot, INIX and customer code, however this is not enforced.

Returns

ER_INCO_NO_ERROR on success

ER_INCO_RPC_NOT_A_TICKET if Ticket is not a ticket (i.e. not negative)

See also Return Values from Asynchronous Procedures and Variable Readings in Synchronous Calling of Asynchronous Procedures

INCO32_EXPORT uint32 WINAPI ProcedureExAddResult	(	int32	Ticket,
		const void *	Result,
		uint32	auResultSize = 8,
		uint32	auType = DF_INCO_TYPE_DOUBLE,
		const char *	ResultName = NULL
	)

Called by an asynchronous procedure to return a result value.

When an asynchronous part of a procedure wants to return one or more values, it calls this function before calling ReturnAsyncCallTicket(). If this function is called multiple times (or by multiple asynchronous parts), multiple results are stored in the order of the calls. The caller of the asynchronous procedure, if interested, can later fetch the returned values using CallProcedureExResult() (this happens automatically in CallProcedureExSync()).

Parameters

Ticket	The ticket that the synchronous part of the procedure got from CheckoutAsyncCallTicket().
Result	Pointer to the value to be set, e.g. a uint32* or double* for typical numerical results or a char* for strings.
auResultSize	Size of the value stored at Result in bytes, e.g. sizeof(uint32) = 4 or sizeof(double) = 8 for typical numerical results or the string length plus one (for the terminating zero) for strings.
auType	An INCO type constant from <inco_32/indeldefs.h> such as DF_INCO_TYPE_UINT32, DF_INCO_TYPE_DOUBLE, DF_INCO_TYPE_STRING etc., matching Result and auResultSize.
ResultName	A string specifying the name under which the result can later be retrieved using CallProcedureExResultByName(), if NULL (the default) or empty, the result is anonymous.

Returns

ER_INCO_NO_ERROR on success

ER_INCO_RPC_NOT_A_TICKET if Ticket is not a ticket (i.e. not negative)

ER_INCO_RPC_RESULT_BUFFER_TO_SMALL if the specified result is too large to fit into the ring buffer for asynchronous results

See also Return Values from Asynchronous Procedures and Variable Readings in Synchronous Calling of Asynchronous Procedures

INCO32_EXPORT void WINAPI PushDeferredCallTicket

(

int32

Ticket

)

Called by a deferred CallProcedure handler to put a ticket back on libinco_32's stack.

This function is used in the inner workings of Synchronous Calling of Asynchronous Procedures and is not of general interest. See CDeferredProcedureCallData::Perform() in libinix for an example of its use.

INCO32_EXPORT void WINAPI ReturnAsyncCallTicket

(

int32

Ticket

)

Called by an asynchronous procedure when an asynchronous action finishes.

When an asynchronous part of a procedure finishes, it calls this function to return the ticket that its invoker got from CheckoutAsyncCallTicket() to libinco_32. Libinco_32 considers a procedure finished when all checked out tickets have been returned.

If Ticket is 0, this function does nothing. If it is called with any other non-ticket (i.e. positive) value, or if it is called too many times with the same ticket (more times than CheckoutAsyncCallTicket()), an assertion failure occurs.

See also Details in Synchronous Calling of Asynchronous Procedures

INCO32_EXPORT int32 WINAPI ReturnAsyncCallTicketAfterCallHasFinished	(	int32	aiMyTicket,
		int32	aiTicketToWaitFor
	)

Called by an asynchronous procedure to declare an asynchronous action completed as soon as another asynchronous procedure finishes.

Used when an asynchronous procedure A calls another asynchronous procedure B, and A can only be considered finished when B is finished as well (in other words, the call to B is an asynchronous part of A). This function does not wait for B to finish, it merely instructs libinco_32 to perform (the equivalent of) ReturnAsyncCallTicket(aiMyTicket) later and returns immediately.

If aiTicketToWaitFor is not a ticket (negative) but a success/error code (zero/positive), aiMyTicket is immediately returned to libinco_32 and this function returns the non-ticket aiTicketToWaitFor. Therefore, it can be used as a transparent wrapper around CallProcedureEx() as seen in this common idiom, which does the right thing whether or not ProcB is asynchronous and whether or not the call to it succeeds:

uint32 INCOProcA() {
    int32 err = ReturnAsyncCallTicketAfterCallHasFinished(
        CheckoutAsyncCallTicket(),
        CallProcedureEx(".", "Cmd.ProcB(17:l)")
    );
    if (err > 0) {
        yell("Error!");
        return 1;
    }
    else return 0;
}

Returns

Zero on success, aiTicketToWaitFor if it is not a ticket.

See also Synchronous Calls Within Asynchronous Procedures in Synchronous Calling of Asynchronous Procedures