PREV TOC HOME INDEX NEXT


ms_setbrdparm( )

Cautions | Errors | Example | See Also

Name: int ms_setbrdparm (devh, param, valuep)
Inputs:

int devh

  • MSI board device handle

unsigned long param

  • device parameter defined name

void * valuep

  • pointer to parameter value
Returns:

0 on success

-1 on failure

Includes:

srllib.h

dtilib.h

msilib.h

Category:

Configuration

Mode:

synchronous

Platform:

DI, HDSI, Springware

Description

The ms_setbrdparm( ) function is used to change board parameters.

Parameter

Description

devh valid board device handle returned by a call to ms_open( )
param parameter whose value is to be altered. Table 4 contains a description of MSI device parameters, listed alphabetically. Note: On DM3 boards, only MSG_DISTINCTRNG is supported for the ms_setbrdparm( ) function.
valuep void pointer to location containing the parameter value

Note: Calling this function may cause the available resource count to change.
When parm_id = MSG_ZIPENA and value = MS_ZIPENABLE, one resource will be used.
When parm_id = MSG_ZIPENA and value = MS_ZIPDISABLE, one resource will be freed.

Cautions

Table 4. MSI Board/Device Parameters 

Parameter ID

Description

MSG_DBOFFTM

Defines the minimum length of time (50 ms units) before an off-hook transition is detected. Off-hook debounce time range: 0-3CH, where 0 = the value used to disable the offhook debounce; default = 3H. A pointer to a short containing this duration is passed as the valuep parameter.

Note: This parameter is not supported on DM3 boards.

MSG_DBONTM

Defines the minimum length of time (50 ms units) before an on-hook transition is detected. On-hook debounce time range: 5-3CH, default: 1EH. A pointer to a short containing this duration is passed as the third parameter.

The MSG_DBONTM value must be set to a greater unit than MSG_MAXFLASH. If set to a lesser unit, the unit will automatically be made equal to or 1 unit greater than MSG_MAXFLASH.

Note: This parameter is not supported on DM3 boards.

MSG_DISTINCTRNG

For ms_setbrdparm( ), this parameter initializes distinctive ringing and associates a cadence ID with a user-defined distinctive ring cadence. The cadence ID can then be used in the ms_genringex( ) function.

Note: This parameter is supported on DM3 boards for the ms_setbrdparm( ) function only.

For ms_getbrdparm( ), this parameter returns a filled-in MS_CADENCE structure containing the distinctive ring cadence pattern and length for the cadence ID specified in the cadid field.

When initializing distinctive ringing using the ms_setbrdparm( ) function, the valuep parameter must point to a data structure. For details, see the description of MS_CADENCE.

Note: Distinctive ring and board-level ring cadence are mutually exclusive except in the case where the cadence lengths are identical. You will get an E_MSRNGCADCNFLCT error if the MSG_PDRNGCAD or MSG_UDRNGCAD board-level ring cadence is currently set to a cadence that does not match the distinctive ring cadence length. For example, if MSG_UDRNGCAD is set to a cadence length of 4, you cannot initialize distinctive ring Group A, which uses a length of 6 seconds.

MSG_MAXFLASH

Defines a maximum length of time (50 ms units) for a station to be in an on-hook state before a hook flash signal is detected. Maximum hook flash time range: 5-3CH, default = 14H. A pointer to a short containing this duration is passed as the third parameter.

Note: This parameter is not supported on DM3 boards.

MSG_MINFLASH

Defines a minimum length of time (50 ms units) for a station to be in an on-hook state before a hook flash signal is detected. Minimum hook flash time range: 2-14H, default = 6H. A pointer to a short containing this duration is passed as the third parameter.

Note: This parameter is not supported on DM3 boards.

MSG_PDRNGCAD

This parameter is used to select one of the following predefined ring cadence patterns on the MSI board. The default value (in seconds) is 6.

Note: This parameter is not supported on DM3 boards.

Value

Cadence Pattern

1
1 on
5 off

2
1 on
2.75 off

3
1.5 on
3 off

4
1 on
4.25 off

5
.5 on, 2.5 off
.5 on, 2.5 off

6
2 on
4 off

Note: Board-level ring cadence and distinctive ring are mutually exclusive except in the case where the cadence lengths are identical. You will get an E_MSRNGCADCNFLCT error if a distinctive ring is currently initialized through MSG_DISTINCTRNG and you set a MSG_PDRNGCAD board-level ring cadence with a length that does not match the distinctive ring length. For example, when using distinctive ring Group A, which has a cadence length of 6-seconds, you cannot set MSG_PDRNGCAD to the predefined cadence patterns that do not have a 6-second cycle.

MSG_RING

This parameter is used to find out whether the board supports ringing capabilities. For a ringing board, the parameter value returned is MS_RNGBRD and for a non-ringing board, the parameter value is MS_NORNGBRD.

Note: This parameter is supported on DM3 boards for the ms_getbrdparm( ) function only.

MSG_RNGCAD

This parameter is used to get the ring cadence pattern. The length of this parameter, in bytes, is variable and is determined by the number of bits of the active period cadence information specified. The first byte of this parameter, specifies the total number (count) of cadence bits being specified. A zero value for this first byte indicates the default number of bits (currently 8) is being specified. The next byte(s) correspond to the bit pattern(s).

Note: This parameter is not supported on DM3 boards.

MSG_UDRNGCAD

User Defined Ring Cadence: This parameter is used to set the default board-level ring cadence (the repeating pattern of ringing ON/OFF durations to a user-defined value for all stations attached to an MSI board).

Note: This parameter is not supported on DM3 boards.

The ring cadence is 1/3 active and 2/3 inactive. The active pattern defines an ON/OFF sequence of ringing in units of 250 ms and is specified in the value pointed to by valuep. The value can be from 2 to 7 bytes, depending upon the duration of the active cycle and subject to the active cycle length, which can be modified through the downloadable parameter file, RING.PRM. (MSI boards only)

Byte 1 specifies the total number of bits in the active period, ranging from 04H to 18H (4 - 24 bits). Since each bit represents a 250 ms duration, the active period can range from 1 second to 6 seconds.

Bytes 2 - 7 (the number of bytes depends upon the value specified in Byte 1) specifies the active period ringing pattern, with each bit representing the state of the ring current (1=ON, 0=OFF) for a 250 ms duration in a sequence from left to right (high-order bits before low-order bits).

The inactive cycle is a mandatory period of no ringing that is twice the active cycle duration. It is not specified by the user but is created implicitly from the active cycle duration.

The default active ring cycle is specified by the RING.PRM download parameter file. (MSI boards only) If no download parameter file is used, the default active cycle is 2 seconds. Also see Table  5, "MSI Ring Cadence Examples" and Figure 1, "Ring Cadence Examples".

Note: When you want to implement a given cadence pattern, you can use the following formula to determine how much to pad the active period with a trailing off-time period so that the total off time is correct. (For multiple ring cadence patterns, calculate the on-time as the entire period from the beginning of the first on-time to the end of the last on-time).

trailing-off-time = 1/3 total-off-time - 2/3 on-time
or
trailing-off-time = (total-off-time - (2 * on-time))/3

For the MSI/SC-R boards only: Even though the ring cadence may be defined as beginning with a ring ON, the ms_genringex( ) or ms_genring( ) function may ring a station beginning at any point in the ring cycle.

Board-level ring cadence and distinctive ring are mutually exclusive except in the case where the cadence lengths are identical.

You will get an E_MSRNGCADCNFLCT error if a distinctive ring is currently initialized through MSG_DISTINCTRNG and you set a MSG_UDRNGCAD board-level ring cadence with a length that does not match the distinctive ring length. For example, when using distinctive ring Group A, which has a cadence length of 6-seconds, you cannot set MSG_UDRNGCAD to a cadence length other than 6-seconds.

If a user defines a new cadence with a greater active cycle length during run time, the current system wide total cycle length is increased to match it. When this occurs, all other defined cadences are padded with silence.

System wide total cycle lengths cannot be reduced during run time. The active cycle length may be reduced during system initialization via the RING.PRM file which, in turn, will reduce the total cycle length. (MSI boards only)

MSG_ZIPENA

The zip tone setting. MS_ZIPENABLE enables zip tone generation. MS_ZIPDISABLE disables zip tone generation. Default = MS_ZIPENABLE.

Note: This parameter is not supported on DM3 boards.

MSCB_ND

Defines the notify-on-add tone generated to notify conference parties that a party has joined or left the conference. valuep must be set to point to an MS_NCB structure that specifies tone characteristics. Note that the pulse repetition field is ignored by the function. See MS_NCB for structure details.

Note: This parameter is not supported on DM3 boards.

MSCB_ZIP

Zip tone controls the characteristics of the tone generated to notify a party that they are about to be connected with a call. The volume, tone frequency, and duration fields of the MS_NCB structure are set but the pulse repetition field is ignored by the function.

Note: This parameter is not supported on DM3 boards.

Table 5. MSI Ring Cadence Examples

Desired Cadence

(seconds)

Parameter Value

(hexadecimal)

Example Number

Ring ON Time (embedded off time)

Ring OFF Time

Total Bits (byte 1)

Active Pattern (bytes 2-n)

Single Ring Patterns:

1
.75
7.5
0B
E000
2 [A]
1
2
04
F0
3 [2]
1
2.75
05
F0
4 [4]
1
4.25
07
F0
5 [1] [B]
1
5
08
F0
6
1.25
4.75
08
F8
7 [3]
1.5
3
06
FC
8
1.5
3.75
07
FC
9 [6]
2
4
08
FF

Double Ring Patterns:

10 [5]
.5, (.25), .5
2.5
05
D8
11
.5, (.25), .5
4
07
D8
12
1, (.75), 1
5.5
0B
F1E0

Triple Ring Patterns:

13
1, (.5), .25, (.25), .25
4.5
09
F280
14 [C]
1, (.5), .25, (.25), .25
5.25
0A
F280
15
1, (1), .25, (.25), .25
5.5
0B
F-A-
16
.5, (.25), .5, (.25), 1
5
0A
DBC0

[1] - [6] These show the predefined cadences for the MSG_PDRNGCAD parameter. [A] - [C] These examples are shown in Figure1.

Figure 1. Ring Cadence Examples

Errors

If this function returns -1 to indicate failure, obtain the reason for the error by calling the SRL standard attribute function ATDV_LASTERR( ) or ATDV_ERRMSGP( ) to retrieve either the error code or a pointer to the error description, respectively.

Refer to the error type tables found in Chapter 5, "Error Codes". Error defines can be found in dtilib.h or msilib.h.

Example 

#include <windows.h>         /* For Windows applications only */
#include <errno.h>
#include "srllib.h"
#include "dtilib.h"
#include "msilib.h"  
main()
{
   int   devh;              /* Board device descriptor variable */
   char  cadence[7];        /* Cadence parameter array */  
   if ((devh = ms_open("msiB1", 0)) == -1) {
      printf("Error opening msiB1 : errno = %d\n", errno);
      exit(1);
   }  
   /*
    * Set cadence bit pattern
    * (Active cadence : 1 sec on, 0.75 secs off, 1 sec on)
    * (Inactive period : 5.5 secs off)
    */
   cadence[0] = 0x0b; /* Bit pattern 11 bits wide */
   cadence[1] = 0xf1; /* Pattern : 11110001 */
   cadence[2] = 0xeo; /* Pattern : 11100000 */  
   /* Set ring cadence to the user-defined pattern */
   if (ms_setbrdparm(devh,MSG_UDRNGCAD,(void *)&cadence[0])) == -1){
      printf("Error setting board parameter : %s\n", ATDV_ERRMSGP(devh));
      exit(1);
   }  
   /* Predefined selection 3 from Table 1 */
   cadence[0] = 3;  
   /* Set ring-cadence to predefined pattern 3 */
   if (ms_setbrdparm(devh,MSG_PDRNGCAD,(void *)&cadence[0])) == -1){
      printf("Error setting board parameter : %s\n", ATDV_ERRMSGP(devh));
      exit(1);
   }  
   if (ms_close(devh) == -1) {
      printf("Error Closing msiB1 : errno - %d\n", errno);
      exit(1);
   }
}

See Also

PREV TOC HOME INDEX NEXT

Click here to contact Telecom Support Resources

Copyright 2003, Intel Corporation
All rights reserved
This page generated January, 2003