nccGetLineStatus

Retrieves a snapshot of the port status and stores it in an NCC_LINE_STATUS structure.

Prototype

DWORD nccGetLineStatus ( CTAHD linehd, NCC_LINE_STATUS *linestatus, unsigned linestatussize, NCC_CALLHD callhd[], unsigned callhdsize )

Argument

Description

linehd

Line handle used to open the NCC API instance.

linestatus

A pointer to the NCC_LINE_STATUS structure to receive the information:

typedef struct
{
  DWORD size;          /* No of bytes written to by linestatus      */ 
  DWORD state;         /* Current state of line                     */ 
  DWORD pendingcmd;    /* Last command not ack'd by board           */ 
  char protocol[NCC_MAX_PNAME+1]; /* Array of protocols on line     */ 
  CTA_MVIP_ADDR port;  /* MVIP address of port                      */ 
  unsigned numcallhd;  /* Number of unreleased call handles         */ 
} NCC_LINE_STATUS;

See the Details section for field descriptions.

linestatussize

The amount of memory available at status. This value must be large enough to receive the NCC_LINE_STATUS size return value.

callhd

An array of call handles to be set to the values of calls on this line that have not been released. Set this value to NULL if you do not want to get a list of all the call handles on the line.

callhdsize

The size in bytes of the callhd array. This value is ignored if callhd is NULL.

Return values

Return value

Description

SUCCESS

 

CTAERR_BAD_ARGUMENT

An argument is invalid or not usable.

CTAERR_BAD_SIZE

A size argument is invalid.

CTAERR_INVALID_HANDLE

The protocol is not running on the specified handle.

CTAERR_SVR_COMM

A server communication error occurred.

Details

nccGetLineStatus retrieves the status of the specified line. If the application provides a buffer that is large enough, this function retrieves a list of call handles existing on the line. Upon returning from the function, the NCC_LINE_STATUS size field contains the actual number of bytes written.

The NCC_LINE_STATUS structure contains the following fields:

Field

Description

size

Number of bytes written at the address pointed to by linestatus.

state

Current line state. Can be any of the following:

  • NCC_LINESTATE_UNINITIALIZED

  • NCC_LINESTATE_IDLE

  • NCC_LINESTATE_BLOCKING

  • NCC_LINESTATE_OUT_OF_SERVICE

  • NCC_LINESTATE_ACTIVE

pendingcmd

The last line command issued that the board has not yet acknowledged. This field is set when a line control command is sent to the board, and cleared on the next event that corresponds to the acknowledgment of the pending command.

Possible values are:

  • (0) No command pending.

  • NCC_PENDINGCMD_BLOCK_CALLS

  • NCC_PENDINGCMD_UNBLOCK_CALLS

  • NCC_PENDINGCMD_START_PROTOCOL

  • NCC_PENDINGCMD_STOP_PROTOCOL

protocol

Arrays containing names of protocols running on this line.

port

MVIP address of call control resource (port), if needed. Specified with ctaOpenServices.

numcallhd

Number of unreleased call handles, starting from index 0.

See also

nccGetCallStatus, nccGetExtendedCallStatus