path: root/doc/devel/calendar/cal-client/tmpl/cal-client.sgml

<!-- ##### SECTION Title ##### -->
CalClient

<!-- ##### SECTION Short_Description ##### -->
GTK+ object for communication with personal calendar server.

<!-- ##### SECTION Long_Description ##### -->
  <para>
    The #CalClient object provides a nice GTK+ wrapper for the CORBA
    interfaces that are used to communicate between calendar clients
    and the personal calendar server in the user's Wombat daemon.
  </para>

  <para>
    After a #CalClient object is created with cal_client_new(), it
    should be asked to send a request to the personal calendar server
    to load or create a calendar based on its URI.  The server will
    asynchronously notify the client about completion of the request,
    and will return an appropriate result code; this should be noted
    by the client with the <link
    linkend="CalClient--cal-loaded">cal_loaded</link> signal.
  </para>

  <para>
    When a client asks the server to update or delete a calendar
    component from the storage, the server will do so and then notify
    all the clients about the update or removal.  This is the core of
    the model/view split between calendar clients and the storage in
    the personal calendar server.  Clients should watch the <link
    linkend="calclient-obj-updated">obj_updated</link> and <link
    linkend="calclient-obj-removed">obj_removed</link> signals on the
    CalClient objects they create so that they can be notified about
    changes in the storage.
  </para>

<!-- ##### SECTION See_Also ##### -->
  <para>

  </para>


<!-- ##### MACRO CAL_CLIENT ##### -->
  <para>
    Casts a #GtkObject to a #CalClient.
  </para>

@obj: A GTK+ object.


<!-- ##### ENUM CalClientLoadStatus ##### -->
  <para>
    These values describe the status of a calendar load or create
    request.  After asking a calendar factory to load or create a
    calendar, the provided listener will get notification about the
    result in asynchronous fashion.  Such notification is represented
    by one of these enumeration values.  For values other than
    #CAL_CLIENT_LOAD_SUCCESS, the #CalClient object will not accept
    any other operations on the calendar and it should just be
    destroyed.
  </para>

@CAL_CLIENT_LOAD_SUCCESS: Indicates a successful load or create
  operation; the corresponding calendar is ready for use.

@CAL_CLIENT_LOAD_ERROR: Indicates an error while loading or creating
  the calendar.

@CAL_CLIENT_LOAD_IN_USE: Indicates that a create request failed
  because the specified calendar was already being used by another
  client.

@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: Indicates an error due to
  trying to load a calendar for which a backend type is not present.

<!-- ##### ENUM CalClientGetStatus ##### -->
  <para>
    These values describe the result of the cal_client_get_object()
    function.
  </para>

@CAL_CLIENT_GET_SUCCESS: Indicates a successful get operation.

@CAL_CLIENT_GET_NOT_FOUND: Indicates that the requested object was
  not found.

@CAL_CLIENT_GET_SYNTAX_ERROR: Indicates a syntax error when parsing
  the requested object.  This could indicate a bug in the calendar
  client libraries or in the Wombat server.

<!-- ##### FUNCTION cal_client_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION cal_client_load_calendar ##### -->
<para>

</para>

@client: 
@str_uri: 
@Returns: 


<!-- ##### FUNCTION cal_client_create_calendar ##### -->
<para>

</para>

@client: 
@str_uri: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_n_objects ##### -->
<para>

</para>

@client: 
@type: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_object ##### -->
<para>

</para>

@client: 
@uid: 
@ico: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_uid_by_pilot_id ##### -->
<para>

</para>

@client: 
@pilot_id: 
@uid: 
@Returns: 


<!-- ##### FUNCTION cal_client_update_pilot_id ##### -->
<para>

</para>

@client: 
@uid: 
@pilot_id: 
@pilot_status: 


<!-- ##### FUNCTION cal_client_get_uids ##### -->
<para>

</para>

@client: 
@type: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_events_in_range ##### -->
<para>

</para>

@client: 
@start: 
@end: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_alarms_in_range ##### -->
<para>

</para>

@client: 
@start: 
@end: 
@Returns: 


<!-- ##### FUNCTION cal_client_get_alarms_for_object ##### -->
<para>

</para>

@client: 
@uid: 
@start: 
@end: 
@alarms: 
@Returns: 


<!-- ##### FUNCTION cal_client_update_object ##### -->
<para>

</para>

@client: 
@ico: 
@Returns: 


<!-- ##### FUNCTION cal_client_remove_object ##### -->
<para>

</para>

@client: 
@uid: 
@Returns: 


<!-- ##### SIGNAL CalClient::cal-loaded ##### -->
  <para>
    This signal is emitted some time after the calendar clients sends
    a load or create request to the personal calendar server.  The
    server will notify the client asynchronously of the completion of
    the request.  The @status parameter indicates the status of the
    request.
  </para>

@client: Calendar client which received the notification.
@status: Status of the request.  See the description of
  #CalClientLoadStatus for more details.

<!-- ##### SIGNAL CalClient::obj-updated ##### -->
  <para>
    This signal is emitted when the calendar clients receives
    notification of a calendar component's data being changed in the
    personal calendar server.  Graphical clients may want to get the
    new version of the object and update their display, for example.
  </para>

@client: Calendar client which received the notification.
@uid: Unique identifier of the calendar component that changed in the
  personal calendar server's storage.

<!-- ##### SIGNAL CalClient::obj-removed ##### -->
  <para>
    This signal is emitted when the calendar client receives
    notification for a calendar component being removed from the
    storage in the personal calendar server.  Graphical clients may
    want to delete the corresponding object from their display, for
    example.
  </para>

@client: Calendar client which received the notification.
@uid: Unique identifier of the calendar component that was removed
  from the personal calendar server's storage.

<!--
Local variables:
mode: sgml
sgml-parent-document: ("../../../evolution-devel-guide.sgml" "book" "refsect2" "")
End:
-->