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...

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	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...

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...

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	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...

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...

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.

Detailed Description

Function Documentation

INCO32_EXPORT uint32 WINAPI CallProcedure	(	const char *	TargetPath,
		const char *	CallProcedure,
		double *	Result
	)

Remote procedure call.

Calls procedure ItemPath on target TargetPath and stores the return value, cast to a double, in *Result.

Note: This function can not properly handle RPCs with asynchronous actions, because it can't wait for its asynchronous part. Use CallProcedureEx if asynchronously executing procedures needs to be called.

Parameters

TargetPath	Definition of the TargetPath
CallProcedure	Definition of the CallProcedure(Ex) syntax
Result	Pointer to a `double` into which the function writes the value returned by the remote procedure

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT int32 WINAPI CallProcedureEx	(	const char *	TargetPath,
		const char *	CallProcedure,
		double *	SyncResult = `NULL`
	)

Remote procedure call (extended).

Replaces CallProcedure() and adds support for asynchronous procedures. Calls procedure CallProcedure on target TargetPath and stores any return value, cast to a double, in *SyncResult. If the called procedure is asynchronous, this function returns before the asynchronous part of the procedure action has completed.

Parameters

TargetPath	Definition of the TargetPath
CallProcedure	Definition of the ItemPath
SyncResult	Will be set to the return value of synchronously executing procedures. If NULL is passed (default), the result will be ignored. If CallProcedure is an asynchronous procedure, then SyncResult will not be altered (because such a function does not return any synchronous result).

Returns: A ticket (negative number) or an error (see Error returned by INCO functions).

Typical use case: CallProcedureEx() is a perfect replacement for CallProcedure(). Therefore, whenever CallProcedure() can be used, you may prefer using CallProcedureEx(). In some certain use cases, it may be more straight-forward to use CallProcedureExSync().

See also: Use case: INCO procedure without asynchronous part
Use case: INCO procedure with asynchronous part
Use case: INCO procedure with asynchronous part returning results
Use case: INCO procedure with asynchronous part returning named results

INCO32_EXPORT uint32 WINAPI CallProcedureExResult	(	const char *	TargetPath,
		int32	Ticket,
		void *	Result = `NULL`,
		uint32	BufferSize = `8`,
		uint32	TypeFlags = `DF_INCO_TYPE_NUMBER_VALUE`,
		char *	ResultName = `NULL`,
		uint32	ResultNameBufSize = `0`
	)

Get the next asynchronous result (or application error) of a remote procedure call (CallProcedureEx).

Get the next available (means: not yet gotten) result that was returned by the asynchronous part of the procedure that returned Ticket. The function implicitly waits indefinitely for the asynchronous part of the procedure to complete. The caller task will therefore be blocked until the async part has finished. (Note that in the case of process-internal calls (TargetPath is "."), this may be dangerous! See CallProcedureExWait() for details.)

There are two pieces of information that are considered "results", both returned by the asynchronous part of a procedure:

Zero or one application error (if any)
Zero or multiple results (or named results)

The function is used to get these results. The results can either be get as "number values" cast to a double (by passing DF_INCO_TYPE_NUMBER_VALUE for TypeFlags) or as "type safe" values by passing one of the other supported types (see <inco_32/indeldefs.h>).

The same result can exactly be read once. This is the case because the result will be removed from the internal buffer after being read. Result values that are not explicitly removed from libinco_32's storage by calling this funtion will eventually be dropped anyway if required to free up space for the results of newer asynchronous procedure calls.

To mention it explictly: To check whether a asynchronous call which does not return any results (such as the CINOSMcRobot::Off command) returned an application error, you need to call this function with Result set to NULL.

Parameters

TargetPath	Definition of the TargetPath. The name of the target to which Ticket belongs. Must exactly match the target name that was passed to the CallProcedureEx() call that produced Ticket, behavior is undefined if different names that refer to the same target are used (with/without server name, with / or \ as separator, aliases, etc.).
Ticket	The ticket that belongs to the asynchronous part of the procedure of which this function returns the next result. The value of Ticket is usually returned by CallProcedureEx().
Result	If not NULL (NULL is default), then the result value will be written to the memory pointed to by Result. Note that the function writes at most BufferSize [Bytes]. If the result is a string, it will always be zero-terminated (even if truncated). Truncation is indicated by returning ER_INCO_RPC_RESULT_BUFFER_TO_SMALL, and in this case the result will not be removed from storage, so that another call with a sufficiently sized buffer can get its entire value.
BufferSize	Memory size in [Bytes] where Result points to. The function will at most write this amount of data to Result
TypeFlags	Any supported type (DF_INCO_TYPE_) as defined in <inco_32/indeldefs.h> can be passed. The function expects the passed type to match the type of the result. Example: If the asynchronous part of an INOS procedure uses pMsg->AddResult((uint8)77), then the caller must pass DF_INCO_TYPE_UINT8 There's an exception to the rule above: Any number value (except (u)int64) can automatically be converted to a double by passing DF_INCO_TYPE_NUMBER_VALUE. Alternatively, pass DF_INCO_FLAG_GET_RESULT_TYPE to get the type (as defined in <inco_32/indeldefs.h>) of the result, instead of its value. Pass DF_INCO_FLAG_GET_RESULT_LENGTH to get its length in bytes (mainly used for strings, where it includes the terminating zero). In these two cases, Result* must be a pointer to a `uint32` and BufferSize must be `sizeof(uint32)` = 4, and the result will (of course) not be removed from the internal buffer and thus the caller can get the actual result by a subsequent call to this function.
ResultName	[out] Optional pointer to a string buffer that will take the result name, if any. The name will not be set if the pointer is NULL (default).
ResultNameBufSize	Buffer size (= string length + 1) in [Bytes] of the available buffer ResultName. The function will at most write ResultNameBufSize - 1 Bytes of the result name and will ensure that the string in ResultName will be zero-terminated.

Returns: On success: ER_INCO_NO_ERROR; If the procedure returned no results and no application error, only an indication that it is done (only for calls to external targets): ER_INCO_RPC_NO_RETURN_VALUE; If all results (or completion indication or application error) have already been retrieved or were dropped to free up space because they were not retrieved in time (or no results were returned for process-internal calls): ER_INCO_RPC_UNKNOWN_TICKET; On INCO failure: Any INCO error, as defined in <inco_32/errinco.h>; If the procedure was interrupted by a target reset: ER_INCO_RPC_INTERRUPTED. No results are available in that case.; Application error: If the asynchronous part of the procedure encountered any problem, the application error will be returned on the first call to this function for a given ticket. See Application errors: McRobot, INIX and customer code. Additional results may still be available after that.

See also: Use case: INCO procedure without asynchronous part
Use case: INCO procedure with asynchronous part
Use case: INCO procedure with asynchronous part returning results
Use case: INCO procedure with asynchronous part returning named results
Return Values from Asynchronous Procedures and Variable Readings in Synchronous Calling of Asynchronous Procedures

INCO32_EXPORT uint32 WINAPI CallProcedureExResultByName	(	const char *	TargetPath,
		int32	Ticket,
		const char *	ResultName,
		void *	Result,
		uint32	BufferSize = `8`,
		uint32	TypeFlags = `DF_INCO_TYPE_NUMBER_VALUE`
	)

Get the next asynchronous named result (or application error) of a remote procedure call (CallProcedureEx).

This function is very similar to CallProcedureExResult(). The only difference is that this function does not return the 'next result' but the result with the name referred to by ResultName. Similar to CallProcedureExResult(), once a certain result has been read, it can't be read again. This is true independently of whether you use CallProcedureExResult() or CallProcedureExResultByName() the second time.

Lets make an example to clarify this: Assume there are three results for a certain ticket. Assume they have the name "Result1", "Result2" and "Result3". If the caller performs the following code (pseudocode):

1 CallProcedureExResultByName(..., "Result2", ...);

Then the following is true:

1 CallProcedureExResult(...); // return the value of "Result1"

2 CallProcedureExResult(...); // return the value of "Result3"

Parameters

TargetPath	Definition of the TargetPath
ResultName	Zero terminated string of the result name

See also: Use case: INCO procedure without asynchronous part
Use case: INCO procedure with asynchronous part
Use case: INCO procedure with asynchronous part returning results
Use case: INCO procedure with asynchronous part returning named results

INCO32_EXPORT uint32 WINAPI CallProcedureExSync	(	const char *	TargetPath,
		const char *	CallProcedure,
		void *	Result = `NULL`,
		uint32	BufferSize = `8`,
		uint32	TypeFlags = `DF_INCO_TYPE_NUMBER_VALUE`
	)

Remote procedure call (extended). If the procedure has an asynchronous part, the function will wait for it to complete.

Calls procedure CallProcedure on target TargetPath. If the called procedure is asynchronous, this function implicitly waits for the asynchronous part of the procedure action to complete.

Parameters

TargetPath	Definition of the TargetPath
CallProcedure	Definition of the ItemPath
Result	If not NULL (default) and the procedure has no asynchronous part, then the synchronous result value will be set and Result is expected to be of type `double` (and accordingly BufferSize* = `sizeof(double)` = 8 and TypeFlags = DF_INCO_TYPE_NUMBER_VALUE). If the procedure has an asynchronous part and the asynchronous part returns at least one result, this function will return the first result and write it to Result (if it's not NULL). Note that all results (except the first one) are lost, because the caller doesn't get the ticket. Use CallProcedureEx() if you want to get more than one result.

Typical use case: Using CallProcedureExSync() makes sense if the programmer knows that the remote procedure does either have no asynchronous part, or it has an asynchronous part and returns zero or one result.

Note that for process-internal calls (TargetPath = "."), the included waiting may carry a risk of deadlocking - see CallProcedureExWait() for details.

See also: Use case: INCO procedure without asynchronous part for a code exmaple.

INCO32_EXPORT uint32 WINAPI CallProcedureExWait	(	const char *	TargetPath,
		int32	Ticket,
		int32	TimeoutMs = `-1`
	)

Wait for the asynchronous part of a remote procedure call (CallProcedureEx) to finish (optionally with timeout).

This function is usually used waiting for the asynchronous part shouldn't be done infinitely. If waiting infinitely is ok, it's slightly more efficiently to use CallProcedureExResult directly.

Parameters

TargetPath	Definition of the TargetPath. The name of the target to which Ticket belongs. Must exactly match the target name that was passed to the CallProcedureEx() call that produced Ticket, behavior is undefined if different names that refer to the same target are used (with/without server name, with / or \ as separator, aliases, etc.).
Ticket	Should be a valid ticket previously returned by CallProcedureEx()
TimeoutMs	Timeout used while waiting for the asynchronous part in [ms]. If -1 is passed, then the call will block forever, until the asynchronous part completed, or an error occurs. If 0 is passed, then the function will not wait but instead just check whether the asynchronous part has already completed and will return immediately. This can be used for "polling". Note that, depending on the used OS (Windows vs. Linux), the smallest applicable timeout may be around 10ms. Thus, even if you pass 1ms here, it'll probably result in 10ms.

Returns: ER_INCO_NO_ERROR if the async part referred to by Ticket has completed, or the INCOServer has detected that it was interrupted by a target reset (check for return value ER_INCO_RPC_INTERRUPTED from CallProcedureExResult() to detect the latter situation).; ER_INCO_RPC_WAIT_TIMEOUT if the async part has not yet completed and waiting for it has timed out (or there was no waiting because TimeoutMs = 0).; An INCO error code (see <inco_32/errinco.h>) in case of INCO communication problems (e.g. INCOServer not running). Note that this function does not return application errors, therefore, it can't be used to check whether an async part has completed with success or error. Instead, it can just be used to check whether the async part has finished.; This function does NOT return application errors and reply codes (i.e. the errors set by MsgError & co in McRobot). Always use CallProcedureExResult for that purpose.

See also: Use case: INCO procedure without asynchronous part
Use case: INCO procedure with asynchronous part
Use case: INCO procedure with asynchronous part returning results
Use case: INCO procedure with asynchronous part returning named results

Typical use case: CallProcedureExWait() is usually only used if the programmer wants to wait with a timeout. For all other cases, CallProcedureExResult is the preferred way to wait for the completion for the asynchronous procedure becuase it does not only wait, but also return any occurred application error.

No guarantees are made about the accuracy of the timeout duration. The given number is a lower bound, but the total execution time of the function may be longer than that, since various parts of its internal implementation are not counted against the total.

If the called procedure is not in the same process, but the call goes to an external target via INCOServer (i.e. TargetPath is not "."), this function must only be called by the same thread that made the original CallProcedureEx() call. For calls within a process, no such restriction exists and any number of threads can wait.

For process-internal calls, be careful when using this function, particularly with infinite timeout: Make sure that by waiting, you are not inadvertently blocking the action that you are waiting for, causing a deadlock. In particular, this can happen in the following two situations:

The asynchronous action waited for is queued to be executed in the same thread that calls CallProcedureExWait(). Putting that thread to sleep now means that it never gets to attend its queue.
The thread that calls CallProcedureExWait() is holding some lock that the thread running the asynchronous action needs to acquire before or during the action.

Within another INCO procedure in particular, a better solution than

1 CallProcedureExWait(".", CallProcedureEx(".", "Cmd.Proc()"));

is usually

 ReturnAsyncCallTicketAfterCallHasFinished(
     CheckoutAsyncCallTicket(),
     CallProcedureEx(".", "Cmd.Proc()")
 );

INCO32_EXPORT uint32 WINAPI GetBlock16	(	const char *	TargetPath,
		uint32	SourceAddress,
		uint16 *	Data,
		uint32	Number
	)

Read raw data in 16 bytes chungs from the target.

Same as GetBlock8, but reads Number times 16 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 32 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 16 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlock32	(	const char *	TargetPath,
		uint32	SourceAddress,
		uint32 *	Data,
		uint32	Number
	)

Read raw data in 32 bytes chungs from the target.

Same as GetBlock8, but reads Number times 32 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 32 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 32 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlock64	(	const char *	TargetPath,
		uint32	SourceAddress,
		uint64 *	Data,
		uint32	Number
	)

Read raw data in 64 bytes chungs from the target.

Same as GetBlock8, but reads Number times 64 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 32 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 64 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlock8	(	const char *	TargetPath,
		uint32	SourceAddress,
		uint8 *	Data,
		uint32	Number
	)

Reads raw data in 8 byte chunks from the target.

Reads Number of bytes of data from the memory at SourceAddress in the INCO target TargetPath and copies that data into the buffer pointed to by Data. The function assumes that Data is at least as big as Number bytes.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 32 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 32 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlockEx16	(	const char *	TargetPath,
		uint64	SourceAddress,
		uint16 *	Data,
		uint32	Number
	)

Read raw data in 16 bytes chungs from the target.

Same as GetBlockEx8, but reads Number times 16 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 64 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 16 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlockEx32	(	const char *	TargetPath,
		uint64	SourceAddress,
		uint32 *	Data,
		uint32	Number
	)

Read raw data in 32 bytes chungs from the target.

Same as GetBlockEx8, but reads Number times 32 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 64 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 32 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlockEx64	(	const char *	TargetPath,
		uint64	SourceAddress,
		uint64 *	Data,
		uint32	Number
	)

Read raw data in 64 bytes chungs from the target.

Same as GetBlockEx8, but reads Number times 64 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 64 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 64 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI GetBlockEx8	(	const char *	TargetPath,
		uint64	SourceAddress,
		uint8 *	Data,
		uint32	Number
	)

Reads raw data in 8 byte chunks from the target.

Reads Number of bytes of data from the memory at SourceAddress in the INCO target TargetPath and copies that data into the buffer pointed to by Data. The function assumes that Data is at least as big as Number bytes.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 64 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Parameters

TargetPath	Definition of the TargetPath
SourceAddress	The 64 bit memory address (target side)
Data	Pointer to the data to which the read data should be written
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Parameters

TargetPath	Definition of the TargetPath. The name of the slave/target for which a previous call failed
Error	The error code that was previously returned by an INCO function, such as CallProcedure(), GetVariable(), PutVariable(), etc.
Description	If Length is unequal 0, this parameter should point to a string buffer. The function copies the error text into that buffer. If Length is 0, then Description should point to a long.
Length	If Length is unequal 0, then its value is the maximum allowed string length (not buffer size!). Internally, the function call 'strncpy(Description, {TheErrorText}, Length);'. If Length is 0, then the function assumes that Description points to a 'long' value and the function writes the required buffer size (not string length!) to it.

Trivial example (complicated):

 // Create a buffer that's huge enough:
 char cErrorMsg[512];
 if( GetErrorDescription("TargetName", uError, cErrorMsg, sizeof(cErrorMsg)-1) == ER_INCO_NO_ERROR ) {
     cout << "Error occurred: " << cErrorMsg << endl;
 }

Example (complicated):

 // Get the required buffer size:
 long iRequiredBufferSize;
 if( GetErrorDescription("TargetName", uError, &iRequiredBufferSize, 0) == ER_INCO_NO_ERROR ) {
     char pErrorText = new char[iRequiredBufferSize];
     // get the actual error text:
     if( GetErrorDescription("TargetName", uError, pErrorText, iRequiredBufferSize-1) == ER_INCO_NO_ERROR ) {
         cout << "Error occurred: " << pErrorText << endl;
         delete [] pErrorText;
     }
 }

INCO32_EXPORT uint32 WINAPI GetMcMessage	(	const char *	TargetPath,
		const char *	MessageHandlerPath,
		uint32	Error,
		char *	Message,
		uint32	Length
	)

Gets the error message of a McRobot message container. Usually, a McRobot based machine has 1 message handler, often located at "Machine.Msg"

Parameters

MessagePath	INCO Path to the message handler. Usually, this path is "Machine.Msg"
Error	The INCO error code as returned from e.g. CallProcedure. Note that this function will care about 'reply codes' by masking them off the error). If the error is not a "McRobot error code" (McRobot errors have the bits set defined by ER_APPERROR_BASE (0x40000000) or ER_APPERROR_CUSTOMER (0x80000000)), this function returns ER_INCO_VAR_NOT_FOUND.
Message	Pointer to the buffer were the message text will be copied
Length	Size of the buffer defined by Message in [Bytes]

Returns: Technically, this function tries to resolve the error passed by param "Error" by accessing the target with GetVariable. Therefore, this function may reutrn any error that may occur by a GetVariable.

INCO32_EXPORT uint32 WINAPI GetVariable	(	const char *	TargetPath,
		const char *	ItemPath,
		void *	Result,
		uint32	Length = `0`
	)

Remote INCO variable read.

Reads variable ItemPath on target TargetPath and stores the return value, cast to a double if Length is 0 or cast to a sequence of chars if length is unequal 0, in *Result. If the variable must be read asynchronously, this function waits for the asynchronous reading to complete. Caution: this waiting means that asynchronous variable getters must be implemented carefully to avoid deadlocks!

Parameters

TargetPath	Definition of the TargetPath
ItemPath	Definition of the ItemPath
Result	Pointer to the buffer to which the value will be written to. Must be a `double` in Length is 0 or a `char` of at least Length* size.
Length	A value of 0 means that a `double` (or any other number item) should be read. A value > 0 means to read a data buffer (usually a char) of size Length*

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlock8, but writes Number times 16 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 32 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 16 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlock8, but writes Number times 32 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 32 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 32 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlock8, but writes Number times 64 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 32 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 64 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO 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.

Writes Number bytes of the data pointed to by Data to the address DestAddress in the INCO target TargetPath. DestAddress may by any address available at the target. Note that the target does usually allow arbitrary memory writes - even if modifying the data will cause target crashes. Therefore, using this function is only recommended in rare cases. The function assumes that Data is at least as big as Number bytes.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 32 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlockEx8, but writes Number times 16 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 64 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 16 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlockEx8, but writes Number times 32 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 64 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 32 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Same as PutBlockEx8, but writes Number times 64 byte of data. This function automatically changes endianness of the data if the target and host endiannes are different.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 32 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 64 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

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.

Writes Number bytes of the data pointed to by Data to the address DestAddress in the INCO target TargetPath. DestAddress may by any address available at the target. Note that the target does usually allow arbitrary memory writes - even if modifying the data will cause target crashes. Therefore, using this function is only recommended in rare cases. The function assumes that Data is at least as big as Number bytes.

Parameters

TargetPath	Definition of the TargetPath
DestAddress	The 64 bit memory address (target side)
Data	Pointer to the data that should be written to the target
Number	Number of 8 byte chunks to transfer

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO32_EXPORT uint32 WINAPI PutVariable	(	const char *	TargetPath,
		const char *	ItemPath,
		const void *	Value,
		uint32	Length = `0`
	)

Remote INCO variable write.

Writes the data pointed to by Value to the INCO variable ItemPath on target TargetPath. The data type to which Value points to depends on the value of Length and must either be a char* (Length > 0) or a double (Length 0).

Parameters

TargetPath	Definition of the TargetPath
ItemPath	Definition of the ItemPath
Value	Pointer to the value that should be written. If Length is 0, Value is expected to point to a `double`. Otherwise a `char*`.
Length	If 0, then Value must point to a `double`. If > 0, this function writes as many bytes as defined by Length to ItemPath.

Returns: An error code from <inco_32/errinco.h> (see Error returned by INCO functions).

INCO variable reading and writing

Remote INCO procedure call (RPC)

Raw target memory access functions

INCO error information

INCO32 version information

Detailed Description

Function Documentation