new_PConnection(3)

NAME

new_PConnection – create a new connection to a PalmOS device

LIBRARY

libpconn

SYNOPSIS

#include <palm.h>

#include <pconn/pconn.h>

PConnection *

new_PConnection(char *device, const pconn_listen_t listenType, const pconn_proto_t protocol, const unsigned short flags);

DESCRIPTION

new_PConnection creates and initializes a new PConnection. This represents a connection to a Palm device, similar to a socket or a telephone. new_PConnection does not connect to the Palm, it merely creates an object that can connect later (in the telephone analogy, it builds the phone but doesn't dial it). The PConnection should be closed and destroyed with PConnClose().

device specifies the pathname of the Palm device, e.g. /dev/cuaa0 for a serial port. If device is NULL or the special string 'stdin', new_PConnection uses standard input and standard output.

listenType specifies the underlying connection to the Palm cradle. It is one of:

LISTEN_SERIAL: Serial connection, including USB connections through /dev/ttyUSB1 under Linux.
LISTEN_NET: TCP connection. The device argument is ignored.
LISTEN_USB: USB connection under *BSD. device should be “/dev/ugen0”.

protocol specifies the software protocol to use to communicate with the Palm cradle. This should be one of:

PCONN_STACK_DEFAULT: Guess at the correct protocol. This will usually be correct, but not always.
PCONN_STACK_FULL: Use the DLP, PADP, and SLP protocols. This is the default for LISTEN_SERIAL and LISTEN_USB.
PCONN_STACK_SIMPLE: Use the DLP protocol and a variant of the NetSync protocol. This is currently only used by Palm m500s and m505s.
PCONN_STACK_NET: Use the DLP and NetSync protocols. This is the default for LISTEN_NET.

flags is the bitwise-or of PCONNFL_TRANSIENT , PCONNFL_PROMPT. and PCONNFL_NOCHANGESPEED. If PCONN_TRANSIENT has been specified, the device may or may not exist at any given time, so that if open() fails to open the device because the file does not exist (ENOENT), this is not an error. This is useful in conjunction with devfs.

If PCONN_PROMPT has been specified, new_PConnection will prompt the user to press the HotSync button on the cradle, after the device has been opened.

If PCONN_NOCHANGESPEED has been specified, new_PConnection will not attept to change the change the speed of the connection that specified by the palm, which breaks modem connections.

RETURN VALUE

new_PConnection returns a pointer to a new PConnection, or NULL in case of error.