.\" Copyright 2007 Mark Ellis (mark_ellis@users.sourceforge.net)
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a copy of
.\" this software and associated documentation files (the "Software"), to deal in
.\" the Software without restriction, including without limitation the rights to
.\" use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
.\" of the Software, and to permit persons to whom the Software is furnished to do
.\" so, subject to the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be included in all
.\" copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
.\" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
.\" SOFTWARE.
.TH SYNCE_INFO_NEW 3  2007-08-26 "The SynCE Project" "http://www.synce.org/"
.SH NAME
synce_info_new \- allocate a new SynceInfo struct
.SH SYNOPSIS
.nf
.B #include <synce.h>
.sp
.BI "SynceInfo *synce_info_new(const char *" device_name );
.sp
.BI "void synce_info_destroy(SynceInfo *" info );
.sp
.BI "const char *synce_info_get_name(SynceInfo *" info );
.BI "bool synce_info_get_os_version(SynceInfo *" info ", int " os_major ", int " os_minor );
.BI "int synce_info_get_build_number(SynceInfo *" info );
.BI "int synce_info_get_processor_type(SynceInfo *" info );
.BI "const char *synce_info_get_os_name(SynceInfo *" info );
.BI "const char *synce_info_get_model(SynceInfo *" info );
.BI "const char *synce_info_get_device_ip(SynceInfo *" info );
.BI "const char *synce_info_get_local_ip(SynceInfo *" info );
.BI "int synce_info_get_partner_id_1(SynceInfo *" info );
.BI "int synce_info_get_partner_id_2(SynceInfo *" info );
.BI "const char *synce_info_get_object_path(SynceInfo *" info );
.BI "pid_t synce_info_get_dccm_pid(SynceInfo *" info );
.BI "const char *synce_info_get_transport(SynceInfo *" info );
.BI "const char *synce_info_get_password(SynceInfo *" info );
.BI "int synce_info_get_key(SynceInfo *" info );
.fi
.SH DESCRIPTION
The
.BR synce_info_new ()
function returns a pointer to a newly allocated and populated
SynceInfo struct for a mobile device.
.sp
If
.BR device_name
is non-NULL, the returned struct relates to a mobile device with that name, or NULL if no device of that name is connected.
.sp
If
.BR device_name
is NULL, the exact behaviour depends on the flavour of dccm daemon in use.
When using
.BR vdccm (1)
or the deprecated
.BR dccm (1),
the current active device is selected. This is usually the last device connected, specifically that described in the active_connection file which is by default
in the ~/.synce/ directory. With 
.BR odccm (1)
the first device connected will be returned. With 
.BR synce-hal
this depends on the device(s) in question, and should be considered undefined.
.sp
This struct should be freed with
.BR synce_info_destroy (3).
.sp
.RS
.nf
typedef struct _SynceInfo {
    pid_t dccm_pid;       /* process id of dccm daemon */
    char* device_ip;      /* device ip address */
    char* local_iface_ip; /* local interface ip address */
    char* password;       /* device password */
    int key;              /* device pass key */
    int os_major;         /* device OS major version */
    int os_minor;         /* device OS minor version */
    int build_number;     /* OS build number */
    int processor_type;   /* device processor */
    int partner_id_1;     /* first sync partner id number */
    int partner_id_2;     /* second sync partner id number */
    char* name;           /* device name */
    char* os_name;        /* device OS name eg. PocketPC */
    char* model;          /* device hardware name */
    char* transport;      /* interface type */
    char* object_path;    /* path to device's information */
} SynceInfo;
.fi
.RE
.PP
These fields must be accessed with the 
.BR synce_info_get_ 
functions. The particular fields populated depend on the flavour of dccm daemon in use.
.sp
The use of
.BR dccm (1)
is deprecated. When using
.BR vdccm (1)
all fields are populated except for 
.BR local_iface_ip 
and 
.BR os_minor .
With 
.BR odccm (1)
and
.BR synce-hal,
.BR dccm_pid,
.BR password,
.BR key,
.BR build_number,
.BR partner_id_1
and 
.BR partner_id_2
are not used.
.BR odccm (1)
also does not populate
.BR local_iface_ip.
.SH "RETURN VALUE"
The
.BR synce_info_new ()
function returns a pointer to the allocated SynceInfo struct,
or NULL if an error occured.
.SH "SEE ALSO"
.BR synce (7),
.BR odccm (1),
.BR vdccm (1)