You are here: SwitchKit® Development Environment Programmer’s Guide > 3 Channel Management > sk_requestOutseizedChannel()

sk_requestOutseizedChannel()

Description

This function is similar to sk_requestChannel(), except that it automatically outseizes the allocated channel with the XL_OutseizeControl message before returning it. If successful, the application receives notification of the channel it was assigned, in addition to any outseize acknowledgments. If there is glare or some other error condition, the LLC automatically tries another channel. This process is repeated up to nRetries times. If there is a problem with all the channels tried, the application is notified with a message containing the last error condition. The aTag and aHandlerFunc are comparable to the tag and handler function arguments passed to sk_sendMsgStruct.

This function causes a RequestChannelAck,an acknowledgment message, to be sent to your application after processing has been completed. This message contains the span and channel allocated to the application module. The channel is now allocated to the application module, and all future messages for that channel are routed to this process.

In order to request a channel without performing an outseize, enter a NULL as the anOutseizeMsg argument.

This function is also available as sk_requestOutseizedChannelOnConnection() and skts_requestOutseizedChannel.

Syntax

int sk_requestOutseizedChannel (char *aChannelGroup, int aNumRetries, XL_OutseizeControl *anOutseizeMsg, void *aTag, HandlerFunc *aHandlerFunc);

int sk_requestOutseizedChannelOnConnection(char *aChannelGroup, int aNumRetries, XL_OutseizeControl *anOutseizeMsg, void *aTag, HandlerFunc *aHandlerFunc, int aConID);

int skts_requestOutseizedChannel( char *aChannelGroup, int aNumRetries, XL_OutseizeControl *anOutseizeMsg, void *aTag, HandlerFunc *aHandlerFunc, int aConID);

Parameters

The function parameters are shown in the next table.

Argument | Description
--- | ---
aChannelGroup | Specifies the channel group
aNumRetries | Limits the number of attempts to find a channel before an error gets send to the application module.
anOutseizeMsg | Pointer to switch API message
aTag | An application defined pointer which will be returned to the application when a handler is invoked.
aHandlerFunc | A pointer to a function that is designed to handle messages.
aConID | aConID is a connection identifier specified at connection creation time and used to indicate which LLC an application wishes to communicate with.

Return Values

Possible return values for this function:

SK_LOST_LLC | This return value indicates your application lost contact with the LLC.
SK_INVALID_OUTSEIZE | This return value indicates the channel group is not configured for outseize traffic.
SK_CHANNEL_PURGING | This return value indicates the channel purged while being outseized by the LLC.