Name

cyg_ppp_options_init — Initialize PPP link options

Synopsis

#include <cyg/ppp/ppp.h>
        

cyg_int32 cyg_ppp_options_init(cyg_ppp_options_t *options);

Description

This function initializes the PPP options, pointed to by the options parameter, to the default state. Once the defaults have been initialized, application code may adjust them by assigning new values to the the fields of the cyg_ppp_options_t structure.

This function returns zero if the options were initialized successfully. It returns -1 if the options argument is NULL, or the options could not be initialized.

The option fields, their functions and default values are as follows:

debug

If set to 1 this enables the reporting of debug messages from the PPP system. These will be generated using diag_printf() and will appear on the standard debug channel. Note that diag_printf() disables interrupts during output: this may cause the PPP link device to overrun and miss characters. It is quite possible for this option to cause errors and even make the PPP link fail completely. Consequently, this option should be used with care.

Default value: 0

kdebugflag

This five bit field enables low level debugging messages from the PPP device layer in the TCP/IP stack. As with the debug option, this may result in missed characters and cause errors. The bits of the field have the following meanings:

BitBSD NameDescription
0x01SC_DEBUGEnable debug messages
0x02SC_LOG_INPKTLog contents of good packets received
0x04SC_LOG_OUTPKTLog contents of packets sent
0x08SC_LOG_RAWINLog all characters received
0x10SC_LOG_FLUSHLog all characters flushed

Default value: 0

default_route

If set to 1 this option causes the PPP subsystem to install a default route in the TCP/IP stack's routing tables using the peer as the gateway. This entry will be removed when the PPP link is broken. If there is already an existing working network connection, such as an ethernet device, then there may already be a default route established. If this is the case, then this option will have no effect.

Default value: 1

modem

If this option is set to 1, then the modem lines will be used during the connection. Specifically, the PPP subsystem will wait until the carrier detect signal is asserted before bringing up the PPP link, and will take the PPP link down if this signal is de-asserted.

Default value: 0

flowctl

This option is used to specify the mechanism used to control data flow across the serial line. It can take one of the following values:

CYG_PPP_FLOWCTL_DEFAULT
The flow control mechanism is not changed and is left at whatever value was set before bringing PPP up. This allows a non-standard flow control mechanism to be used, or for it to be chosen and set by some other means.
CYG_PPP_FLOWCTL_NONE
Flow control is turned off. It is not recommended that this option be used unless the baud rate is set low or the two communicating machines are particularly fast.
CYG_PPP_FLOWCTL_HARDWARE
Use hardware flow control via the RTS/CTS lines. This is the most effective flow control mechanism and should always be used if available. Availability of this mechanism depends on whether the serial device hardware has the ability to control these lines, whether they have been connected to the socket pins and whether the device driver has the necessary support.
CYG_PPP_FLOWCTL_SOFTWARE
Use software flow control by embedding XON/XOFF characters in the data stream. This is somewhat less effective that hardware flow control since it is subject to the propagation time of the serial cable and the latency of the communicating devices. Since it does not rely on any hardware support, this flow control mechanism is always available.

Default value: CYG_PPP_FLOWCTL_HARDWARE

refuse_pap

If this option is set to 1, then the PPP subsystem will not agree to authenticate itself to the peer with PAP. When dialling in to a remote server it is normal to authenticate the client. There are three ways this can be done, using a straightforward login mechanism via the CHAT script, with the Password Authentication Protocol (PAP), or with the Challenge Handshake Authentication Protocol (CHAP). For PAP to work the user and passwd options must be set to the expected values. If they are not, then this option should be set to force CHAP authentication.

Default value: 0

refuse_chap

If this option is set to 1, then the PPP subsystem will not agree to authenticate itself to the peer with CHAP. CHAP authentication will only work if the passwd option has been set to the required CHAP secret for the destination server. Otherwise this option should be disabled.

If both refuse_pap and refuse_chap are set, then either no authentication will be carried out, or it is the responsibility of the chat script to do it. If the peer does not require any authentication, then the setting of these options is irrelevant.

Default value: 0

baud

This option is set to the baud rate at which the serial connection should be run. The default value is the rate at which modems conventionally operate. This field is an instance of the cyg_serial_baud_rate_t enum defined in the serialio.h header and may only take one of the baud rate constants defined in there.

Default value: CYGNUM_SERIAL_BAUD_115200

idle_time_limit

This is the number of seconds that the PPP connection may be idle before it is shut down automatically.

Default value: 60

maxconnect

This causes the connection to terminate when it has been up for this number of seconds. The default value of zero means that the connection will stay up indefinitely, until either end explicitly brings it down, or the link is lost.

Default value: 0

our_address

This is the IP address, in network byte order, to be attached to the local end of the PPP connection. The default value of INADDR_ANY causes the local address to be obtained from the peer.

Default value: INADDR_ANY

his_address

This is the IP address, in network byte order, to be attached to the remote end of the PPP connection. The default value of INADDR_ANY causes the remote address to be obtained from the peer.

Default value: INADDR_ANY

accept_local

This allows the behaviour described above for our_address to be modified. Normally, if our_address is set, then the PPPD will insist that this address be used. However, if this option is also set, the PPPD will accept a value supplied by the peer.

Default value: 0

accept_remote

This allows the behaviour described above for his_address to be modified. Normally, if his_address is set, then the PPPD will insist that this address be used. However, if this option is also set, the PPPD will accept a value supplied by the peer.

Default value: 0

script

This is a pointer to a CHAT script suitable for passing to cyg_ppp_chat(). See Chapter 157, CHAT Scripts for details of the format and contents of this script.

Default value: NULL

user

This array contains the user name to be used for PAP authentication. This field is not used for CHAP authentication. By default the value of this option is set from the CYGPKG_PPP_AUTH_DEFAULT_USER configuration option.

Default value: CYGPKG_PPP_AUTH_DEFAULT_USER

passwd

This array contains the password to be used for PAP authentication, or the secret to be used during CHAP authentication. By default the value of this option is set from the CYGPKG_PPP_AUTH_DEFAULT_PASSWD configuration option.

Default value: CYGPKG_PPP_AUTH_DEFAULT_PASSWD