Instance related functions

Typedefs

typedef VOID(* TcInstanceEvtLinkStatusChange )(TC_INSTANCE instance, TC_LINK_INFO linkInfo, PVOID context)
 This event callback function processes a link status change event.

Functions

TC_STATUS TcInstanceOpenByPort (TC_PORT port, PTC_INSTANCE pInstance)
 It opens a reception/transmission instance of a port given a port handle.
TC_STATUS TcInstanceOpenByName (PCHAR name, PTC_INSTANCE pInstance)
 It opens a reception/transmission instance of a port given the port unique name.
TC_STATUS TcInstanceClose (TC_INSTANCE instance)
 It closes an reception/transmission instance.
TC_PORT TcInstanceGetPort (TC_INSTANCE instance)
 It returns the underlying port handle of an instance.
TC_STATUS TcInstanceRegisterEvtLinkStatusChange (TC_INSTANCE instance, TcInstanceEvtLinkStatusChange eventHandler, PVOID context)
 It registers an event handler that gets called whenever the link status changes.
TC_STATUS TcInstanceSetFeature (TC_INSTANCE instance, ULONG feature, ULONG value)
 It sets a specific feature on the instance.
TC_STATUS TcInstanceQueryFeature (TC_INSTANCE instance, ULONG feature, PULONG pValue)
 It queries a specific feature on the instance.
TC_STATUS TcInstanceReceivePackets (TC_INSTANCE instance, PTC_PACKETS_BUFFER pBuffer)
 It receives packets from a specific port.
HANDLE TcInstanceGetReceiveWaitHandle (TC_INSTANCE instance)
 It returns a Windows waitable handle that gets signalled when some packets are available to be received.
TC_STATUS TcInstanceTransmitPackets (TC_INSTANCE instance, TC_PACKETS_BUFFER buffer)
 It transmits a packets buffer on the port described by a given instance.
TC_STATUS TcInstanceQueryStatistics (TC_INSTANCE instance, PTC_STATISTICS pStatistics)
 It queries the statistics of an instance.

Typedef Documentation

typedef VOID( * TcInstanceEvtLinkStatusChange)(TC_INSTANCE instance, TC_LINK_INFO linkInfo, PVOID context)

This event callback function processes a link status change event.

Parameters:
instance Instance handle on which the event callback function was registered.
linkInfo The new status of the link.
context Context parameter registered when calling TcInstanceRegisterEvtLinkStatusChange.

Function Documentation

TC_STATUS TcInstanceOpenByPort ( TC_PORT  port,
PTC_INSTANCE  pInstance 
)

It opens a reception/transmission instance of a port given a port handle.

Parameters:
port port that the open instance handle will correspond to to.
pInstance pointer to a caller allocated instance handle. On success it will contain an handle to the opened instance.
Returns:
One of the Error codes values.
Note:
The opened instance must be closed with TcInstanceClose.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcInstanceOpenByName ( PCHAR  name,
PTC_INSTANCE  pInstance 
)

It opens a reception/transmission instance of a port given the port unique name.

Parameters:
name Unique name of the port to open, as returned by TcPortGetName.
pInstance pointer to a caller allocated instance handle. On success it will contain an handle to the opened instance.
Returns:
One of the Error codes values.
Note:
The opened instance must be closed with TcInstanceClose.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcInstanceClose ( TC_INSTANCE  instance  ) 

It closes an reception/transmission instance.

Parameters:
instance Handle to the instance to close.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_PORT TcInstanceGetPort ( TC_INSTANCE  instance  ) 

It returns the underlying port handle of an instance.

Parameters:
instance Instance handle
Returns:
handle to the port.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceRegisterEvtLinkStatusChange ( TC_INSTANCE  instance,
TcInstanceEvtLinkStatusChange  eventHandler,
PVOID  context 
)

It registers an event handler that gets called whenever the link status changes.

Parameters:
instance Instance handle
eventHandler Pointer to a function that will be invoked when the link status of the port changes.
context A context parameter that gets passed unmodified to the eventHandler when the handler gets invoked.
Returns:
One of the Error codes values.
Note:
  • It's not possible to register more than one event handler per instance handle
  • I'ts not possible to deregister the event handler. The event handler is registered until the instance handle gets closed.
  • The eventHandler gets invoked on an arbitrary thread.
  • It's not possible to register an eventHandler on an aggregating port.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceSetFeature ( TC_INSTANCE  instance,
ULONG  feature,
ULONG  value 
)

It sets a specific feature on the instance.

Parameters:
instance Instance handle
feature Identifier of the feature. A list of the available features can be found in section Features.
value Value of the feature to be set. Please refer to the documentation of the specific feature you are trying to set in section Features.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceQueryFeature ( TC_INSTANCE  instance,
ULONG  feature,
PULONG  pValue 
)

It queries a specific feature on the instance.

Parameters:
instance Instance handle
feature Identifier of the feature. A list of the available features can be found in section Features.
pValue Pointer to a 32bit integer. On success it will return the value of the feature. Please refer to the documentation in section Features to know what values can be returned by querying a specific feature.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceReceivePackets ( TC_INSTANCE  instance,
PTC_PACKETS_BUFFER  pBuffer 
)

It receives packets from a specific port.

Parameters:
instance Instance handle
pBuffer Pointer to a caller allocated packets buffer handle. On success, if some packets were received, it will contain a valid packets buffer instance. Otherwise it will be set to NULL. On failure, the pointer is not touched.
Returns:
One of the Error codes values.
Note:
  • This API is non-blocking i.e. it returns immediately, even if no packets are available.
  • The returned packets buffer should be released with TcPacketsBufferDestroy.
  • When a valid packets buffer is returned in the pBuffer parameter, the caller owns the packets buffer until it calls TcPacketsBufferDestroy.
  • For performance reasons, the library maintains an internal pool of packets buffers that are returned by this function. It's strongly suggested to release the packets buffers to the library with TcPacketsBufferDestroy as soon the the application is done with the packets contained in the buffer.

Thread safety: this function is thread safe. It's possible to call this function on the same instance from concurrent threads at the same time. Moreover, the returned packets buffers returned by this function can be destroyed (with TcPacketsBufferDestroy) on an arbitrary thread without the need of any synchronization, with the condition that the instance must not be destroyed in the meantime. Also, it's safe to call this function and TcInstanceQueryStatistics from different threads concurrently.

HANDLE TcInstanceGetReceiveWaitHandle ( TC_INSTANCE  instance  ) 

It returns a Windows waitable handle that gets signalled when some packets are available to be received.

Parameters:
instance Instance handle
Returns:
A Win32 handle to wait on with the standard Win32 wait calls like WaitForSingleObject and WaitForMultipleObjects(Ex).
Note:
The event gets signalled when at least "mintocopy" bytes are available in the kernel buffer to be brought to user level with TcInstanceReceivePackets.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceTransmitPackets ( TC_INSTANCE  instance,
TC_PACKETS_BUFFER  buffer 
)

It transmits a packets buffer on the port described by a given instance.

Parameters:
instance Instance handle to the port that has to be used to transmit packets.
buffer Handle to the packets buffer that has to be transmitted.
Returns:
One of the Error codes values.
Note:
  • This function is blocking i.e. it will not return until all the packets have been passed to the transmission engine or an error occurs.
  • When the function returns, the caller is again the owner of the packets buffer and can release it.
  • When this function successfully returns, it means that the packets have all been moved to the tranmission engine, and the board is still transmitting the packets.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized.

TC_STATUS TcInstanceQueryStatistics ( TC_INSTANCE  instance,
PTC_STATISTICS  pStatistics 
)

It queries the statistics of an instance.

Parameters:
instance Instance handle
pStatistics Pointer to a caller allocated statistics handle. On success it will return a valid statistics handle. In case of success, the returned statistics handle should be released with TcStatisticsDestroy.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different instance handles (TC_INSTANCE). Calling this function on the same instance from concurrent threads must be synchronized. Also, it's safe to call this function and TcInstanceReceivePackets from different threads concurrently.


TurboCap API documentation. Copyright (c) 2007-2008 CACE Technologies. All rights reserved.