tfPppSetOption

Jump to: navigation, search

Table of Contents >> Optional Protocols >> PPP Interface


#include <trsocket.h>


int tfPppSetOption (
ttUserInterface interfaceId,
int protocolLevel,
int remoteLocalFlag,
int optionName,
ttConstCharPtr optionValuePtr,
int optionLength
);


Function Description

This function is used to set the PPP options that we wish to negotiate as well as those options that we will allow. This allows us to change the link away from the default parameters described in RFC 1661.


Parameters

  • interfaceHandle
    The interface handle to set the option on.
  • protocolLevel
    The protocol which this option should be applied. Current supported protocols are:
  • TM_PPP_LCP_PROTOCOL
  • TM_PPP_IPCP_PROTOCOL
  • TM_PPP_PAP_PROTOCOL
  • TM_PPP_CHAP_PROTOCOL
  • remoteLocalFlag
    This flag describes whether the option is for what we want to use for our side of the link (TM_PPP_OPT_WANT) or is what we will allow the remote side to use (TM_PPP_OPT_ALLOW), or is what we will NAK the remote side with (TM_PPP_OPT_NAK). Please note that the TM_PPP_OPT_NAK flag is valid only with the TM_IPCP_IP_ADDRESS optionName).
  • optionName
    The name of the option. (See below.)
  • optionValuePtr
    The value of the option. (See below.)
  • optionLength
    The length of the option. (See below.)


LCP (TM_PPP_LCP_PROTOCOL) Options

Option Name Length Meaning
TM_LCP_ADDRCONTROL_COMP 1 A Boolean value specifying whether address field compression should be used.

Default OFF.

TM_LCP_PROTOCOL_COMP 1 A Boolean value specifying whether protocol field compression should be used.

Default OFF.

TM_LCP_MAGIC_NUMBER 1 A Boolean value indicating whether to specify a magic number.

Default OFF.

TM_LCP_MAX_FAILURES 1 Sets the maximum number of LCP configuration failures.

This determines the maximum number of configuration NAKs that will be sent before we reject an option.

Default 5.

TM_LCP_MAX_RECV_UNIT 2 Specifies the largest MRU that we will allow and the default MRU that we want to use.

Default 1500.

TM_LCP_ACCM 4 Specifies the async control character map that we want to use, and if we want to allow the remote side to be able to set his ACCM.

Default 0xffffffff.

TM_LCP_AUTH_PROTOCOL 2 Use when authenticating to our peer, and vice versa (e.g. PAP or CHAP). Possible values are:
  • TM_PPP_PAP_PROTOCOL
  • TM_PPP_CHAP_PROTOCOL
  • TM_PPP_EAP_PROTOCOL

Default No authentication.

TM_LCP_TERM_RETRY 1 Sets the maximum number of Terminate requests that the local peer will send (without receiving a Terminate Ack) before terminating the connection.

Default 3.

TM_LCP_CONFIG_RETRY 1 Sets the maximum number of LCP config requests that will be sent without receiving a LCP ack/nak/reject.

'remoteLocalFlag' has no effect.

Default 10.

TM_LCP_TIMEOUT 1 Sets the LCP retransmission timeout in seconds.

Default 3 seconds.

TM_LCP_QUALITY_PROTOCOL 4 Setting this option enables link quality monitoring. The option value is specified in hundredths of a second, and it configures the maximum time to delay (i.e. LQR timer period) between sending Link-Quality-Report messages (refer to RFC 1989, Reporting-Period field of the Quality-Protocol Configuration Option). This option can be set for either the local or the remote end of the link, however the direction in which it applies is the opposite of what one would expect: when 'remoteLocalFlag' is set to TM_PPP_OPT_WANT, this specifies an option value that we want the remote end of the link to use, and when 'remoteLocalFlag' is set to TM_PPP_OPT_ALLOW, this specifies an option value that we will allow the remote end to configure us to use. If a non-zero option value is specified, the LQR timer is started with the specified timeout period to pace the sending of Link-Quality-Report messages, and this timer is restarted whenever a Link-Quality-Report message is sent. If the specified option value is 0, no LQR timer is used, but instead a Link-Quality-Report message is sent as a response every time one is received from the peer. At least one side of the link must use the LQR timer to pace the sending of Link-Quality-Report messages when link quality monitoring is enabled, therefore this option value should not be set to 0 for both ends of the link.
TM_LCP_CALLBACK 1 TM_CALLBACK_OP_CBCP: A new LCP option that tells Treck what callback operation you want/allow. Presently, the only callback operation supported is CBCP.


LQM (TM_LCP_QUALITY_PROTOCOL) Options

Option Name Length Meaning
TM_LCP_QUALITY_PROTOCOL 4 Setting this option enables link quality monitoring. The option value is specified in hundredths of a second, and it configures the maximum time to delay (i.e. LQR timer period) between sending Link-Quality-Report messages (refer to RFC 1989, Reporting-Period field of the Quality-Protocol Configuration Option). This option can be set for either the local or the remote end of the link, however the direction in which it applies is the opposite of what one would expect: when 'remoteLocalFlag' is set to TM_PPP_OPT_WANT, this specifies an option value that we want the remote end of the link to use, and when 'remoteLocalFlag' is set to TM_PPP_OPT_ALLOW, this specifies an option value that we will allow the remote end to configure us to use. If a non-zero option value is specified, the LQR timer is started with the specified timeout period to pace the sending of Link-Quality-Report messages, and this timer is restarted whenever a Link-Quality-Report message is sent. If the specified option value is 0, no LQR timer is used, but instead a Link-Quality-Report message is sent as a response every time one is received from the peer. At least one side of the link must use the LQR timer to pace the sending of Link-Quality-Report messages when link quality monitoring is enabled, therefore this option value should not be set to 0 for both ends of the link.


IPCP (TM_PPP_IPCP_PROTOCOL) Options

Option Name Length Meaning
TM_IPCP_COMP_PROTOCOL 2 Specifies the type of compression to use over the link (optional).

TM_PPP_COMP_TCP_PROTOCOL selects Van Jacobson header compression. TM_PPP_IPHC_PROTOCOL selects RFC 2507 style IP header compression (you must also call tfUseIpHdrComp() before setting this option).

Default No compression.

TM_IPCP_IPHC_TCP_SPACE 2 IP Header Compression: The maximum number of slots used to store TCP header compression info; this value is determined by the maximum number of concurrent TCP sessions that are expected over this link.

Default 15.

TM_IPCP_IPHC_NON_TCP_SPACE 2 IP Header Compression: The maximum number of slots used to store non-TCP (UDP, etc) header compression info; this value is determined by the maximum number of concurrent non-TCP sessions that are expected across this link.

Default 15.

TM_IPCP_IPHC_MAX_PERIOD 2 IP Header Compression: The maximum interval between sending full headers.

Default 256.

TM_IPCP_IPHC_MAX_TIME 2 IP Header Compression: The maximum time interval, in seconds, between sending full headers.

Default 5 seconds.

TM_IPCP_IPHC_MAX_HEADER 2 IP Header Compression: The largest header size in octets that may be compressed.

Default 168 bytes.

TM_IPCP_MAX_FAILURES 1 Sets the maximum number of IPCP configuration failures. This determines the maximum number of configuration NAKs that will be sent before we reject an option.

Default 5.

TM_IPCP_VJ_SLOTS 1 The number of slots used to store state information for each side of a VJ compressed link. This value is determined by the maximum number of concurrent TCP sessions that you will have.

Default 1 slot.

TM_IPCP_IP_ADDRESS 4 Specifies if we want to allow the remote to set their IP address. See the Setting a PPP IP Address, and the Naking a PPP IP Address sections below.

Default Don't Allow.

TM_IPCP_DNS_PRI 4 Specifies the IP addresses of the Primary DNS Server we will allow the remote to use or the Primary DNS server that we want to us. See the Setting a PPP IP Address section below.

Default Don't Allow

TM_IPCP_DNS_SEC 4 Specifies the IP Address of the Secondary DNS server we will allow the remote to use or the Secondary DNS server that we want to use. See the Setting a PPP IP Address section below.

Default Don't Allow.


IPV6CP (TM_PPP_IPV6CP_PROTOCOL) Options

Option Name Length Meaning
TM_IPV6CP_COMP_PROTOCOL 2 Specifies the type of compression to use over the link (optional). TM_PPP_IPHC_PROTOCOL selects RFC 2507 style IP header compression (you must also call tfUseIpHdrComp() before setting this option).
TM_IPV6CP_IPHC_TCP_SPACE 2 IP Header Compression: The maximum number of slots used to store TCP header compression info; this value is determined by the maximum number of concurrent TCP sessions that are expected over this link.

Default 4.

TM_IPV6CP_IPHC_NON_TCP_SPACE 2 IP Header Compression: The maximum number of slots used to store non-TCP (UDP, etc) header compression info; this value is determined by the maximum number of concurrent non-TCP sessions that are expected across this link.

Default 4.

TM_IPV6CP_IPHC_MAX_PERIOD 2 IP Header Compression: The maximum interval between sending full headers.

Default 256.

TM_IPV6CP_IPHC_MAX_TIME 2 IP Header Compression: The maximum time interval, in seconds, between sending full headers.

Default 5 seconds.

TM_IPV6CP_IPHC_MAX_HEADER 2 IP Header Compression: The largest header size in octets that may be compressed.

Default 168 bytes.


PPP (PPP_PROTOCOL) Options

Option Name Length Meaning
TM_PPP_SEND_BUFFER_SIZE 2 Length of data buffered by the PPP link layer (but not beyond the end of a packet) before the device driver send function is called.

Default 1 byte.

TM_IPCP_RETRY 1 Sets the maximum number of IPCP config requests that will be sent without receiving a IPCP nak/ack/reject.

'remoteLocalFlag' has no effect.

Default 10.

TM_IPCP_TIMEOUT 1 Sets the IPCP retransmission timeout value (in seconds).

'remoteLocalFlag' has no effect.

Default 1 second.


TM_PPP_PROTOCOL Options

Option Name Length Meaning
TM_PPP_SEND_BUFFER_SIZE 2 Length of data buffered by the PPP link layer (but not beyond the end of a packet) before the device driver send function is called.

Default 1 byte.


CBCP Protocol (TM_PPP_CBCP_PROTOCOL) Options

Option Name Length Meaning
TM_CBCP_OP_ROLE 1 Option values:
  • TM_CBCP_ROLE_DEFAULT
  • TM_CBCP_ROLE_CALLER
  • TM_CBCP_ROLE_ANSWERER

Describe what role this station plays: caller or answerer. By default, Treck will use the chosen link layer as a hint: client (tfUseAsyncPpp()) = caller and server (tfUseAsyncServerPpp()) = answerer.

TM_CBCP_OP_TYPES 1-3 Option values:
  • TM_CBCP_CTYPE_NOCALL
  • TM_CBCP_CTYPE_CALLER
  • TM_CBCP_CTYPE_ANSWERER

Specify a list of callback types to allow, one value per byte. In case of multiple matches with the peer, the first match is chosen. The option values, respectively, are: start PPP without calling back, answerer calls back at caller-specified address and answerer calls back at pre-specified address.

TM_CBCP_OP_CALL_DELAY 1 The number of seconds to wait before calling back. Only the caller station can dictate the callback delay, as stated in the CBCP draft. The default delay is 10 seconds.

Default value: 10

TM_CBCP_OP_ADDRESS 2 The callback address (phone number).

This is a formatted, binary value that takes the form described in the CBCP draft:

  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
  | Address Type  |   ASCIIZ address
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

Address Type is a byte value. The only supported type is TM_CBCP_ATYPE_PSTN (1), which means the address that follows is a null terminated PSTN/ISDN ASCII value. Valid characters are 0-9, *, #, T, P, W, @, comma, space, dash, and parentheses.


TM_CBCP_OP_RETRY 1 Maximum number of send attempts. If Treck PPP does not receive a useful response after this many retransmissions, the interface will close.

Default value: 10

TM_CBCP_OP_TIMEOUT 1 The time between sends attempts (seconds).

Default value: 3

TM_CBCP_OP_DISC_DELAY 1 The delay before disconnecting (seconds). Treck PPP issues a request to the application to hang up the phone in preparation for a callback. Since there may be outbound PPP data in the UART device, Treck PPP will delay the hang up request to avoid losing data, which could cause the callback to fail.

Default value: 2


Setting a PPP IP Address

The following applies to all of the IP Address 'optionNames':

  • TM_IPCP_IP_ADDRESS
  • TM_IPCP_DNS_PRI
  • TM_IPCP_DNS_SEC

If tfPppSetOption() is not used with the IP address 'optionName' (default) then the remote will not be allowed to request its IP and/or DNS IP addresses.

If tfPppSetOption() is called with the IP address 'optionName', the 'remoteLocalFlag' set to TM_PPP_OPT_ALLOW, and the 'optionValuePtr' pointing to an IP address of 0.0.0.0, then the remote will be allowed to request that its IP/DNS IP address be set to anything except 0.0.0.0.

For example:

ttUserIpAddress remoteIpAddress;
remoteIpAddress = inet_addr("0.0.0.0");
tfPppSetOption(interfaceHandle,
               TM_PPP_IPCP_PROTOCOL,
               TM_PPP_OPT_ALLOW,
               TM_IPCP_IP_ADDRESS,
               (const char *)&remoteIpAddress,
               4);

If tfPppSetOption() is called with the IP address 'optionName', the 'remoteLocalFlag' set to TM_PPP_OPT_ALLOW, and the 'optionValuePtr' pointing to an IP address other than 0.0.0.0, then two situations may occur. Either the remote will be allowed to set its IP/DNS IP address to this value, or it will be returned this value if it requests 0.0.0.0.

NAKing a PPP IP Address

The following applies only to the IP Address 'optionNames':

  • TM_IPCP_IP_ADDRESS

If tfPppSetOption() is called with the IP address 'optionName', the 'remoteLocalFlag' set to TM_PPP_OPT_NAK, and the 'optionValuePtr' pointing to an IP address other than 0.0.0.0, then we will NAK this IP address to the remote indefinitely. For example:

ttUserIpAddress remoteIpAddress;
remoteIpAddress = inet_addr("172.16.0.1");
tfPppSetOption(interfaceHandle,
               TM_PPP_IPCP_PROTOCOL,
               TM_PPP_OPT_NAK,
               TM_IPCP_IP_ADDRESS,
               (const char *)&remoteIpAddress,
               4);

If in addition tfPppSetOption() is called with the IP address 'optionName', the 'remoteLocalFlag' set to TM_PPP_OPT_ALLOW, and the 'optionValuePtr' pointing to an IP address of 0.0.0.0, then the remote will be allowed to request that its IP address be set to anything except 0.0.0.0, but only in the first request. For example:

ttUserIpAddress remoteIpAddress;
remoteIpAddress = inet_addr("172.16.0.1");
tfPppSetOption(interfaceHandle,
               TM_PPP_IPCP_PROTOCOL,
               TM_PPP_OPT_NAK,
               TM_IPCP_IP_ADDRESS,
               (const char *)&remoteIpAddress,
               4);
remoteIpAddress = inet_addr("0.0.0.0");
tfPppSetOption(interfaceHandle,
               TM_PPP_IPCP_PROTOCOL,
               TM_PPP_OPT_ALLOW,
               TM_IPCP_IP_ADDRESS,
               (const char *)&remoteIpAddress,
               4);

PAP (TM_PPP_PAP_PROTOCOL) Options

Option Name Length Meaning
TM_PAP_USERNAME Any Sets the username to use with PAP Client.

Default NONE.

TM_PAP_PASSWORD Any Sets the password to use with PAP

Default NONE.

TM_PAP_RETRY 1 Sets the maximum number of PAP authentication requests that will be sent without receiving an ACK/NAK.

'remoteLocalFlag' has no effect.

Default 10.

TM_PAP_TIMEOUT 1 Sets the PAP retransmission timeout value in seconds.

'remoteLocalFlag' has no effect.

Default 3 seconds.


CHAP (TM_PPP_CHAP_PROTOCOL) Options

Option Name Length Meaning
TM_CHAP_USERNAME Any Sets the username to use with CHAP Client.

Default NONE.

TM_CHAP_SECRET Any Sets the secret to use with CHAP.

Default NONE.

TM_CHAP_MSSECRET Any Sets the secret to use with MS-CHAPv1.

Please note that Treck requires that this secret be specified using the little endian 16-bit Unicode representation. For example, a password of "foo" would be represented as: 0x66 0x00 0x6f 0x00 0x6f 0x00

Default NONE.

TM_CHAP_RETRY 1 Sets the maximum number of CHAP challenges that will be sent without receiving a CHAP response.

'remoteLocalFlag' has no effect.

Default 10.

TM_CHAP_TIMEOUT 1 Sets the CHAP retransmission timeout value in seconds.

'remoteLocalFlag' has no effect.

Default 3 seconds.

TM_CHAP_ALG_ADD 1 Add a CHAP algorithm. You don't need to add TM_CHAP_MD5, because it is automatically added when TM_PPP_CHAP_PROTOCOL is used. You may add TM_CHAP_MSV1 in order to support MS_CHAP version 1.
TM_CHAP_ALG_DEL 1 Delete a CHAP algorithm. You may delete TM_CHAP_MD5 (standard CHAP) or TM_CHAP_MSV1 (MS-CHAP version 1)


'optionLength' should be the size of the data type, 'optionValuePtr' is pointing to, except for the TM_PAP_USERNAME, TM_PAP_PASSWORD, TM_CHAP_USERNAME, and TM_CHAP_SECRET options, where 'optionValuePtr' points to the first byte of an array, and where 'optionLength' is the size of the array 'optionValuePtr' is pointing to.

Data Types

Protocol Level Option Name Data Type
TM_PPP_LCP_PROTOCOL TM_LCP_ADDRCONTROL_COMP unsigned char
TM_LCP_PROTOCOL_COMP unsigned char
TM_LCP_MAGIC_NUMBER unsigned char
TM_LCP_MAX_RECV_UNIT unsigned short
TM_LCP_ACCM unsigned long
TM_LCP_AUTH_PROTOCOL unsigned short
TM_LCP_TERM_RETRY unsigned char
TM_LCP_CONFIG_RETRY unsigned char
TM_LCP_TIMEOUT unsigned char
TM_PPP_IPCP_PROTOCOL TM_IPCP_COMP_PROTOCOL unsigned short
TM_IPCP_VJ_SLOTS unsigned char
TM_IPCP_IP_ADDRESS unsigned long
TM_IPCP_RETRY unsigned char
TM_IPCP_TIMEOUT unsigned char
TM_PPP_PAP_PROTOCOL TM_PAP_USERNAME char
TM_PAP_PASSWORD char
TM_PAP_RETRY unsigned char
TM_PAP_TIMEOUT unsigned char
TM_PPP_CHAP_PROTOCOL TM_CHAP_USERNAME char
TM_CHAP_SECRET char
TM_CHAP_RETRY unsigned char
TM_CHAP_TIMEOUT unsigned char
TM_PPP_PROTOCOL TM_PPPSEND_BUFFER_SIZE unsigned short


Returns

  • TM_ENOERROR
    Success.
  • TM_EINVAL
    Invalid parameter.
  • TM_ENOPROTOOPT
    'protocolLevel' or 'optionName' is invalid.


Table of Contents >> Optional Protocols >> PPP Interface