Handle functions

Handles are used when an entity that wishes to access the stream may survive the stream without knowing that it outlived it. For example, an object reading a message may have a handle to a stream, but the message selection object that spawned it (and which owns the stream) may have gone away. A stream can be closed or recycled while handles are pointing at it, but it is not completely freed until all handles are gone. A stream may have an arbitrary number of handles.

• mail_makehandle

  MAILHANDLE *mail_makehandle(MAILSTREAM *stream);
  

  
  stream

  Stream to make handle to.

  This function creates and returns a handle to the stream.

• mail_free_handle

  void mail_free_handle(MAILHANDLE **handle);
  

  
  handle

  Pointer to handle to release.

  This function frees the handle and notifies the stream that it has one fewer handle. If this is the last handle on the stream and the stream has been closed, then the stream is freed.

• mail_stream

  MAILSTREAM *mail_stream(MAILHANDLE *handle);
  

  
  handle

  Pointer to handle to look up.

  This function returns the stream associated with the handle if (and only if) the stream still represents the same MAIL connection associated with the handle. Otherwise, NIL is returned (meaning that there is no active stream associated with this handle).