1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
.\" new_PConnection.3
.\"
.\" Copyright 2001, Andrew Arensburger.
.\" You may distribute this file under the terms of the Artistic
.\" License, as specified in the README file.
.\"
.\" $Id: new_PConnection.3,v 1.5 2002/07/04 21:23:11 azummo Exp $
.\"
.\" This man page uses the 'mdoc' formatting macros. If your 'man' uses
.\" the old 'man' package, you may run into problems.
.\"
.Dd Aug 15, 2001
.Dt new_PConnection 3
.Sh NAME
.Nm new_PConnection
.Nd create a new connection to a PalmOS device
.Sh LIBRARY
.Pa libpconn
.Sh SYNOPSIS
.Fd #include <palm.h>
.Fd #include <pconn/pconn.h>
.Ft PConnection *
.Fn new_PConnection "char *device" "const pconn_listen_t listenType" "const pconn_proto_t protocol" "const unsigned short flags"
.Sh DESCRIPTION
.Nm
creates and initializes a new
.Ft PConnection .
This represents a connection to a Palm device, similar to a socket or
a telephone.
.Nm
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
.Ft PConnection
should be closed and destroyed with
.Fn PConnClose .
.Pp
.Fa device
specifies the pathname of the Palm device, \fIe.g.\fR
.Pa /dev/cuaa0
for a serial port. If
.Fa device
is NULL or the special string 'stdin',
.Nm
uses standard input and standard output.
.Pp
.Fa listenType
specifies the underlying connection to the Palm cradle. It is one of:
.Bl -tag -width "LIS" -compact -offset indent
.It Dv LISTEN_SERIAL
Serial connection, including USB connections through
.Pa /dev/ttyUSB1
under Linux.
.It Dv LISTEN_NET
TCP connection. The
.Fa device
argument is ignored.
.It Dv LISTEN_USB
USB connection under *BSD.
.Fa device
should be
.Dq Dv /dev/ugen0 .
.El
.Pp
.Fa protocol
specifies the software protocol to use to communicate with the Palm
cradle. This should be one of:
.Bl -tag -width "LIS" -compact -offset indent
.It Dv PCONN_STACK_DEFAULT
Guess at the correct protocol. This will usually be correct, but not
always.
.It Dv PCONN_STACK_FULL
Use the DLP, PADP, and SLP protocols. This is the default for
.Dv LISTEN_SERIAL
and
.Dv LISTEN_USB .
.It Dv PCONN_STACK_SIMPLE
Use the DLP protocol and a variant of the NetSync protocol. This is
currently only used by Palm m500s and m505s.
.It Dv PCONN_STACK_NET
Use the DLP and NetSync protocols. This is the default for
.Dv LISTEN_NET .
.El
.Pp
.Fa flags
is the bitwise-or of
.Dv PCONNFL_TRANSIENT
,
.Dv PCONNFL_PROMPT .
and
.Dv PCONNFL_NOCHANGESPEED .
If
.Dv 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.
.Pp
If
.Dv PCONN_PROMPT
has been specified,
.Nm
will prompt the user to press the HotSync button on the cradle, after
the device has been opened.
.Pp
If
.Dv PCONN_NOCHANGESPEED
has been specified,
.Nm
will not attept to change the change the speed of the connection that
specified by the palm, which breaks modem connections.
.Sh RETURN VALUE
.Nm
returns a pointer to a new
.Ft PConnection ,
or NULL in case of error.
.\" XXX - Code example
.Sh SEE ALSO
.Xr libpconn 3 ,
.Xr PConnClose 3,
.Xr PConn_bind .
|
