impcurl

https://docs.rs/impcurl/1.0.0
Admin
impcurl is a Rust library providing wrapper bindings for curl with support for HTTP sessions,...
Tokens:83,851
Snippets:741
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Search Queries

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.check_code.html?search=std%3A%3Avec

These are example search queries that might be useful when looking for related functionality or patterns within Rust documentation.

```rust
std::vec
```

```rust
u32 -> bool
```

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Handling File Metadata with and_then

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates chaining fallible operations to get file metadata and its modification time. This example shows how `and_then` can be used with system calls that return Results.

```Rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### TryInto Implementation Example

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.WsFrame.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the usage of the TryInto trait, which allows attempting a conversion from one type to another, returning a Result.

```rust
impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,
{
    type Error = <U as TryFrom<T>>::Error;

    #[inline]
    fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error> {
        U::try_from(self)
    }
}
```

--------------------------------

### Into Implementation Example

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.WsFrame.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the Into trait implementation, which provides a consuming conversion from one type to another, assuming a From implementation exists.

```rust
impl<T, U> Into<U> for T
where
    U: From<T>,
{
    #[inline]
    fn into(self) -> U {
        U::from(self)
    }
}
```

--------------------------------

### Basic unwrap usage

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Demonstrates the basic usage of `unwrap` to get the value from an `Ok` variant. Panics if the `Result` is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

--------------------------------

### Type Parameter Resolution Example

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.complete_connect_only_websocket_handshake_with_multi.html?search=u32+-%3E+bool

Illustrates a scenario where 'u32' might be used as a generic parameter and suggests searching for 'i32' if 'u32' is not found, particularly in the context of boolean comparisons.

```rust
u32 matches **K**
```

--------------------------------

### into_ok for infallible Results

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Example of `into_ok`, an experimental API that returns the contained `Ok` value without panicking. It's a compile-time safeguard against Results that cannot fail.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Type 'u32' as Generic Parameter Example

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.check_code.html?search=u32+-%3E+bool

Illustrates a scenario where 'u32' is used as a generic parameter, with a note suggesting 'i32' might be more appropriate.

```rust
u32 matches K
```

--------------------------------

### Getting Mutable References with `as_mut()`

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Shows how to use `as_mut()` to get mutable references to the contained values within a `Result`. This allows in-place modification of `Ok` or `Err` values.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Get File Descriptor Sets

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html

Populates file descriptor sets for reading, writing, and error conditions, and determines the maximum file descriptor.

```rust
pub fn fdset(
    &self,
    readfds: *mut c_void,
    writefds: *mut c_void,
    errfds: *mut c_void,
    max_fd: &mut c_int,
) -> Result<()>
```

--------------------------------

### Flattening Nested Results Example

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=u32+-%3E+bool

Demonstrates flattening multiple levels of nested Results. Flattening removes one level of nesting at a time.

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Unwrapping with a Default Value using `unwrap_or`

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Shows how to get the `Ok` value or a provided default if the Result is `Err`. The `default` argument is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Getting References with `as_ref()`

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Illustrates the `as_ref()` method for obtaining references to the contained values of a `Result` without consuming it. This is useful for inspecting values.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Handling File Metadata Operations with `and_then`

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Shows how to chain fallible operations like retrieving file metadata and its modification time. `and_then` is used to process the successful result of `metadata()` and attempt to get the `modified` time, propagating any `NotFound` errors.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### EasySession Initialization

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Creates a new EasySession, which manages a single curl easy handle. Returns an error if curl_easy_init returns null.

```rust
pub fn new(api: &'a CurlApi) -> Result<Self> {
    let easy = unsafe { (api.easy_init)() };
    if easy.is_null() {
        return Err(ImpcurlError::NullEasyHandle);
    }
    Ok(Self {
        api,
        easy,
        headers: ptr::null_mut(),
    })
}
```

--------------------------------

### Any::type_id implementation

Source: https://docs.rs/impcurl/1.0.0/impcurl/enum.ImpcurlError.html?search=u32+-%3E+bool

Gets the TypeId of the implementing type.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### MultiSession::timeout_ms

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=

Gets the timeout in milliseconds for the next transfer.

```APIDOC
## MultiSession::timeout_ms

### Description
Gets the timeout in milliseconds for the next transfer.

### Method
`timeout_ms`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
None

### Response
#### Success Response
- **timeout** (*`c_long`*) - The timeout value in milliseconds.

### Request Example
```rust
let timeout = multi_session.timeout_ms()?;
println!("Timeout: {}ms", timeout);
```

### Response Example
```rust
// Returns the timeout in milliseconds.
```
```

--------------------------------

### Converting Result to Option with `ok()`

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Shows how to use the `ok()` method to convert a `Result<T, E>` into an `Option<T>`, consuming the original Result. `Ok` values become `Some`, and `Err` values become `None`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### MultiSession::timeout_ms

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=std%3A%3Avec

Gets the recommended timeout in milliseconds for the next operation.

```APIDOC
## MultiSession::timeout_ms

### Description
Returns the recommended timeout in milliseconds for the next socket operation. This value is determined by cURL based on the state of the managed easy handles.

### Signature
`pub fn timeout_ms(&self) -> Result<c_long>`

### Returns
* `Result<c_long>` - A Result containing the timeout in milliseconds as a `c_long` on success, or an error on failure.
```

--------------------------------

### EasySession::new

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=std%3A%3Avec

Creates a new EasySession, which represents a single transfer session using libcurl's easy interface. It initializes an easy handle and prepares it for use.

```APIDOC
## EasySession::new

### Description
Creates a new `EasySession`, which represents a single transfer session using libcurl's easy interface. This method initializes an easy handle and prepares it for subsequent operations.

### Function Signature
```rust
pub fn new(api: &'a CurlApi) -> Result<Self>
```

### Parameters
* `api` (*CurlApi) - A reference to the `CurlApi` struct containing function pointers for libcurl operations.

### Returns
* `Result<EasySession>` - Returns `Ok(EasySession)` upon successful creation of the easy handle. Returns `Err(ImpcurlError::NullEasyHandle)` if `curl_easy_init` returns a null pointer.
```

--------------------------------

### timeout_ms

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=u32+-%3E+bool

Gets the maximum timeout in milliseconds that libcurl will wait for any of the operations to complete.

```APIDOC
## timeout_ms

### Description
Retrieves the maximum timeout in milliseconds that libcurl will wait for any of the ongoing operations to complete.

### Method
`timeout_ms(&self) -> Result<c_long>`

### Returns
- `Result<c_long>`: The timeout in milliseconds, or an error code if it cannot be determined.
```

--------------------------------

### MultiSession::timeout_ms

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html

Gets the maximum timeout in milliseconds for the current multi-handle operations.

```APIDOC
## MultiSession::timeout_ms

### Description
Retrieves the maximum timeout in milliseconds that the multi-handle needs to wait for any of its easy handles to complete an operation. This is useful for determining the next polling interval.

### Signature
`pub fn timeout_ms(&self) -> Result<c_long>`

### Returns
* `Result<c_long>` - A Result containing the timeout in milliseconds on success, or an error on failure.
```

--------------------------------

### into_ok

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Returns the contained Ok value, but never panics. This is a nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Method
`into_ok()`

### Parameters
None

### Request Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

### Response
#### Success Response
The contained `Ok` value.

#### Response Example
```rust
"this is fine"
```
```

--------------------------------

### timeout_ms

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the maximum time in milliseconds that the multi handle can be left to run before a timeout occurs.

```APIDOC
## timeout_ms

### Description
Retrieves the recommended timeout in milliseconds for the multi handle's operations.

### Method
`timeout_ms(&self) -> Result<c_long>`

### Returns
- `Result<c_long>`: The timeout in milliseconds, or an error code if the operation fails.
```

--------------------------------

### EasySession Creation

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new EasySession, which manages a single libcurl easy handle. This session is responsible for the lifecycle of the easy handle, including its cleanup.

```APIDOC
## EasySession::new

### Description
Creates a new `EasySession` instance. This involves initializing a libcurl easy handle. The session manages the lifecycle of this handle, ensuring it's cleaned up properly when the session is dropped.

### Method
```rust
pub fn new(api: &'a CurlApi) -> Result<Self>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Ok(EasySession)`: A new `EasySession` instance if initialization is successful.

#### Error Response
- `ImpcurlError::NullEasyHandle`: If `curl_easy_init` returns a null pointer.
- `ImpcurlError::Curl`: If any other curl-related error occurs during initialization.

### Example
```rust
// Assuming api is an initialized CurlApi struct
match impcurl::EasySession::new(&api) {
    Ok(session) => {
        println!("Easy session created successfully.");
        // Use the session...
    }
    Err(e) => eprintln!("Failed to create easy session: {}", e),
}
```
```

--------------------------------

### timeout_ms

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Gets the maximum time in milliseconds that the multi interface can block waiting for an action before timing out.

```APIDOC
## timeout_ms

### Description
Retrieves the maximum timeout in milliseconds for the multi interface's next operation.

### Method
`timeout_ms(&self) -> Result<c_long>`

### Returns
- `Ok(c_long)`: The timeout in milliseconds. A value of -1 indicates that the multi interface has no specific timeout.
- `Err(Result<()>)`: An error if the operation fails.
```

--------------------------------

### EasySession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.EasySession.html

Constructs a new EasySession. This is the primary way to create a session for making API calls.

```APIDOC
## EasySession::new

### Description
Constructs a new EasySession, which is essential for initiating API interactions.

### Signature
`pub fn new(api: &'a CurlApi) -> Result<Self>`

### Parameters
* **api** (`&'a CurlApi`): A reference to the CurlApi object that the session will use.
```

--------------------------------

### Error::cause implementation for ImpcurlError (Deprecated)

Source: https://docs.rs/impcurl/1.0.0/impcurl/enum.ImpcurlError.html?search=u32+-%3E+bool

Deprecated method for getting the cause of the error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Unsafe `unwrap_err_unchecked` on Ok

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Example illustrating the undefined behavior when `unwrap_err_unchecked` is called on an `Ok` variant. This code should not be run in production.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

--------------------------------

### Unsafe `unwrap_unchecked` on Err

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Example illustrating the undefined behavior when `unwrap_unchecked` is called on an `Err` variant. This code should not be run in production.

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### perform

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=std%3A%3Avec

Runs the multi handle's internal state machine. It should be called whenever the multi handle indicates that it's ready for action (e.g., after a timeout or socket event).

```APIDOC
## perform

### Description
Executes the multi handle's state machine to process transfers.

### Method
`perform(&self, running_handles: &mut i32) -> Result<()>`

### Parameters
- **running_handles** (&mut i32) - A mutable reference to an integer that will be updated with the number of remaining running easy handles.
```

--------------------------------

### MultiSession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=std%3A%3Avec

Creates a new MultiSession instance. This is the entry point for managing multiple cURL easy handles.

```APIDOC
## MultiSession::new

### Description
Creates a new MultiSession instance, which is used to manage multiple cURL easy handles concurrently.

### Signature
`pub fn new(api: &'a CurlApi) -> Result<Self>`

### Parameters
* `api` (*&'a CurlApi*) - A reference to the CurlApi instance.

### Returns
* `Result<Self>` - A Result containing the new MultiSession instance on success, or an error on failure.
```

--------------------------------

### From<T> implementation

Source: https://docs.rs/impcurl/1.0.0/impcurl/enum.ImpcurlError.html?search=u32+-%3E+bool

Returns the argument unchanged.

```rust
fn from(t: T) -> T
```

--------------------------------

### perform

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Runs the multi interface's state machine. This function should be called repeatedly as long as there are transfers running.

```APIDOC
## perform

### Description
Executes the multi interface's internal state machine to process active transfers.

### Method
`perform(&self, running_handles: &mut i32) -> Result<()>`

### Parameters
- `running_handles` (&mut i32): A mutable reference to an integer that will be updated with the number of still running easy handles.
```

--------------------------------

### Error::description implementation for ImpcurlError (Deprecated)

Source: https://docs.rs/impcurl/1.0.0/impcurl/enum.ImpcurlError.html?search=u32+-%3E+bool

Deprecated method for getting a description of the error. Use the Display impl or to_string() instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### Multi Session Initialization

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html

Creates a new MultiSession, which manages a curl multi handle. Returns an error if curl_multi_init returns null.

```rust
pub fn new(api: &'a CurlApi) -> Result<Self> {
    let multi = unsafe { (api.multi_init)() };
    if multi.is_null() {
        return Err(ImpcurlError::NullMultiHandle);
    }
    Ok(Self {
        api,
        multi,
    })
}
```

--------------------------------

### prepare_connect_only_websocket_session

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.prepare_connect_only_websocket_session.html?search=std%3A%3Avec

Prepares a WebSocket session for making search requests. This function takes a CurlApi instance and WebSocket connection configuration to set up the session.

```APIDOC
## Function prepare_connect_only_websocket_session

### Description
Prepares a WebSocket session for making search requests. This function is part of the impcurl library and is used to establish a connection for subsequent search operations.

### Signature
```rust
pub fn prepare_connect_only_websocket_session<'a>(
    api: &'a CurlApi,
    cfg: &WebSocketConnectConfig<'_>,
) -> Result<EasySession<'a>>
```

### Parameters
* `api` (*&'a CurlApi*): A reference to the CurlApi instance.
* `cfg` (*&WebSocketConnectConfig<'_>*): Configuration for the WebSocket connection.

### Returns
* `Result<EasySession<'a>>`: Returns an EasySession on success, or an error if the session preparation fails.
```

--------------------------------

### EasySession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.EasySession.html?search=u32+-%3E+bool

Creates a new EasySession instance. Requires a reference to a CurlApi object and returns a Result.

```rust
pub fn new(api: &'a CurlApi) -> Result<Self>
```

--------------------------------

### MultiSession Creation

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new MultiSession, which manages multiple libcurl easy handles concurrently. This session is responsible for the lifecycle of the multi handle, including its cleanup.

```APIDOC
## MultiSession::new

### Description
Creates a new `MultiSession` instance. This involves initializing a libcurl multi handle, which is used to manage multiple easy handles concurrently. The session manages the lifecycle of this multi handle, ensuring it's cleaned up properly when the session is dropped.

### Method
```rust
pub fn new(api: &'a CurlApi) -> Result<Self>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Ok(MultiSession)`: A new `MultiSession` instance if initialization is successful.

#### Error Response
- `ImpcurlError::NullMultiHandle`: If `curl_multi_init` returns a null pointer.
- `ImpcurlError::Curl`: If any other curl-related error occurs during initialization.

### Example
```rust
// Assuming api is an initialized CurlApi struct
match impcurl::MultiSession::new(&api) {
    Ok(multi_session) => {
        println!("Multi session created successfully.");
        // Use the multi_session...
    }
    Err(e) => eprintln!("Failed to create multi session: {}", e),
}
```
```

--------------------------------

### MultiSession Initialization

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Creates a new MultiSession, which manages a curl multi handle. Returns an error if curl_multi_init returns null.

```rust
pub fn new(api: &'a CurlApi) -> Result<Self> {
    let multi = unsafe { (api.multi_init)() };
    if multi.is_null() {
        return Err(ImpcurlError::NullMultiHandle);
    }
    Ok(Self { api, multi })
}
```

--------------------------------

### Get CurlApi

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides access to the `CurlApi` struct, which holds function pointers to the libcurl library. This allows for inspection or use of the underlying API functions.

```APIDOC
## EasySession::api

### Description
Returns a reference to the `CurlApi` struct associated with this `EasySession`. The `CurlApi` contains function pointers to the underlying libcurl functions, allowing access to the raw API if needed.

### Method
```rust
pub fn api(&self) -> &CurlApi
```

### Parameters
None

### Response
- `&CurlApi`: A reference to the `CurlApi` struct.

### Example
```rust
// Assuming session is an initialized EasySession instance
let curl_api = session.api();
// You can now use curl_api to call libcurl functions directly if needed
```
```

--------------------------------

### MultiSession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html

Creates a new MultiSession instance. This is the entry point for managing multiple cURL handles.

```APIDOC
## MultiSession::new

### Description
Creates a new MultiSession instance, which is used to manage multiple concurrent cURL sessions.

### Signature
`pub fn new(api: &'a CurlApi) -> Result<Self>`

### Parameters
* **api** (*&'a CurlApi*) - A reference to the CurlApi instance.

### Returns
* `Result<Self>` - A Result containing the new MultiSession instance on success, or an error on failure.
```

--------------------------------

### into_err for infallible Results

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Example of `into_err`, an experimental API that returns the contained `Err` value without panicking. It's a compile-time safeguard against Results that cannot succeed.

```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

--------------------------------

### ensure_curl_global_init

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.ensure_curl_global_init.html?search=

Ensures that curl_global_init is called exactly once for the process lifetime. It does not call curl_global_cleanup, as the library remains loaded until process exit. If the initial call fails, subsequent calls will return the same error.

```APIDOC
## ensure_curl_global_init

### Description
Ensures that curl_global_init is called exactly once for the process lifetime. This function manages the initialization of the curl library for the entire process.

### Function Signature
```rust
pub fn ensure_curl_global_init(api: &CurlApi) -> Result<()>
```

### Parameters
* **api** (*&CurlApi*) - An instance of CurlApi, likely used to interact with the underlying curl library.

### Return Value
* **Result<()>** - Returns Ok(()) on success, or an Err if the curl_global_init call fails. Subsequent calls will return the same error if the first one failed.
```

--------------------------------

### and for combining Results

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Demonstrates `and` which returns the second `Result` if the first is `Ok`, otherwise returns the `Err` of the first. Arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));
```

```rust
let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));
```

```rust
let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));
```

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### MultiSession::timeout_ms

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the lowest timeout value in milliseconds among all managed easy handles. This indicates the maximum time to wait before the next poll or action.

```APIDOC
## MultiSession::timeout_ms

### Description
Returns the shortest timeout value in milliseconds required by any of the currently managed easy handles. This is useful for determining the next polling interval.

### Method
`timeout_ms`

### Signature
`pub fn timeout_ms(&self) -> Result<c_long>`

### Returns
* `Result<c_long>` - The timeout value in milliseconds.
```

--------------------------------

### Get Easy Handle

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the raw pointer to the underlying libcurl easy handle. This is useful for advanced configurations or when interacting directly with libcurl functions not exposed by impcurl.

```APIDOC
## EasySession::easy_handle

### Description
Returns the raw pointer to the underlying `curl_easy_handle` (`*mut Curl`). This allows for direct manipulation of the easy handle using libcurl's C API if needed, though caution should be exercised.

### Method
```rust
pub fn easy_handle(&self) -> *mut Curl
```

### Parameters
None

### Response
- `*mut Curl`: A raw pointer to the `Curl` easy handle.

### Example
```rust
// Assuming session is an initialized EasySession instance
let easy_handle_ptr = session.easy_handle();
// Use the raw pointer with libcurl C functions if necessary
```
```

--------------------------------

### ensure_curl_global_init

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.ensure_curl_global_init.html?search=std%3A%3Avec

Ensures that curl_global_init is called exactly once for the process lifetime. This function never calls curl_global_cleanup, as the library stays loaded until process exit. If the first call fails, subsequent calls will return the same error.

```APIDOC
## Function ensure_curl_global_init

### Description
Ensures that `curl_global_init` is called exactly once for the process lifetime. This function never calls `curl_global_cleanup`, as the library stays loaded until process exit. If the first call fails, subsequent calls will return the same error.

### Signature
```rust
pub fn ensure_curl_global_init(api: &CurlApi) -> Result<()>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Result<()>`: Indicates success if the initialization is performed or has already been successfully performed.
```

--------------------------------

### Get Timeout for Multi Handle

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=std%3A%3Avec

Determines the maximum time in milliseconds that the multi handle can be left to wait for activity before a timeout occurs. Returns -1 if no timeout is set.

```rust
pub fn timeout_ms(&self) -> Result<c_long>
{
    let mut timeout_ms: c_long = -1;
    let code = unsafe { (self.api.multi_timeout)(self.multi, &mut timeout_ms) };
    check_multi_code(self.api, code, "curl_multi_timeout")?;
    Ok(timeout_ms)
}
```

--------------------------------

### prepare_connect_only_websocket_session Function Signature

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.prepare_connect_only_websocket_session.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This is the function signature for `prepare_connect_only_websocket_session`. It takes references to `CurlApi` and `WebSocketConnectConfig` and returns a `Result` containing an `EasySession`.

```rust
pub fn prepare_connect_only_websocket_session<'a>(
    api: &'a CurlApi,
    cfg: &WebSocketConnectConfig<'_>,
) -> Result<EasySession<'a>>
```

--------------------------------

### Get Timeout for Multi Handle Operations

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Determines the maximum time in milliseconds that the multi handle can wait for an operation to complete before timing out. Returns -1 if no timeout is set.

```rust
pub fn timeout_ms(&self) -> Result<c_long> {
        let mut timeout_ms: c_long = -1;
        let code = unsafe { (self.api.multi_timeout)(self.multi, &mut timeout_ms) };
        check_multi_code(self.api, code, "curl_multi_timeout")?;
        Ok(timeout_ms)
    }
```

--------------------------------

### Result Implementations

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=

Provides documentation for various methods implemented for the Result type, enabling operations like copying, cloning, transposing, flattening, and checking the status of the result.

```APIDOC
## Implementations

### impl<T, E> Result<&T, E>

#### pub const fn copied(self) -> Result<T, E>

Maps a `Result<&T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### pub fn cloned(self) -> Result<T, E>

Maps a `Result<&T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### impl<T, E> Result<&mut T, E>

#### pub const fn copied(self) -> Result<T, E>

Maps a `Result<&mut T, E>` to a `Result<T, E>` by copying the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

#### pub fn cloned(self) -> Result<T, E>

Maps a `Result<&mut T, E>` to a `Result<T, E>` by cloning the contents of the `Ok` part.

##### Examples
```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

### impl<T, E> Result<Option<T>, E>

#### pub const fn transpose(self) -> Option<Result<T, E>>

Transposes a `Result` of an `Option` into an `Option` of a `Result`.
`Ok(None)` will be mapped to `None`. `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))`.

##### Examples
```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

### impl<T, E> Result<Result<T, E>, E>

#### pub const fn flatten(self) -> Result<T, E>

Converts from `Result<Result<T, E>, E>` to `Result<T, E>`.

##### Examples
```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

Flattening only removes one level of nesting at a time:
```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

### impl<T, E> Result<T, E>

#### pub const fn is_ok(&self) -> bool

Returns `true` if the result is `Ok`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

#### pub fn is_ok_and<F>(self, f: F) -> bool
where F: FnOnce(T) -> bool,

Returns `true` if the result is `Ok` and the value inside of it matches a predicate.

##### Examples
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

#### pub const fn is_err(&self) -> bool

Returns `true` if the result is `Err`.

##### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

#### pub fn is_err_and<F>(self, f: F) -> bool
where F: FnOnce(E) -> bool,

Returns `true` if the result is `Err` and the value inside of it matches a predicate.
```

--------------------------------

### Get File Descriptors for Multi Handle

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=

Retrieves the file descriptors (read, write, error) and the maximum file descriptor number currently in use by the multi handle.

```rust
pub fn fdset(
        &self,
        readfds: *mut c_void,
        writefds: *mut c_void,
        errfds: *mut c_void,
        max_fd: &mut c_int,
    ) -> Result<()> {
        let code = unsafe { (self.api.multi_fdset)(self.multi, readfds, writefds, errfds, max_fd) };
        check_multi_code(self.api, code, "curl_multi_fdset")
    }
```

--------------------------------

### fn hash<__H>(&self, state: &mut __H) -> ()

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Feeds this value into the given `Hasher`.

```APIDOC
## fn hash<__H>(&self, state: &mut __H)

### Description
Feeds this value into the given `Hasher`.
```

--------------------------------

### Get File Descriptor Set for Multi Handle

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=std%3A%3Avec

Retrieves the file descriptor set for read, write, and error conditions from the multi handle. This is used for monitoring socket activity.

```rust
pub fn fdset(
    &self,
    readfds: *mut c_void,
    writefds: *mut c_void,
    errfds: *mut c_void,
    max_fd: &mut c_int,
) -> Result<()>
{
    let code = unsafe { (self.api.multi_fdset)(self.multi, readfds, writefds, errfds, max_fd) };
    check_multi_code(self.api, code, "curl_multi_fdset")
}
```

--------------------------------

### ensure_curl_global_init

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.ensure_curl_global_init.html

Ensures that curl_global_init is called exactly once for the process lifetime. It does not call curl_global_cleanup, meaning the library remains loaded until the process exits. If the initial call to curl_global_init fails, all subsequent calls will return the same error.

```APIDOC
## ensure_curl_global_init

### Description
Ensures that curl_global_init is called exactly once for the process lifetime. This function manages the initialization of the curl library for the entire process. It is designed to be idempotent and safe to call multiple times, guaranteeing that the underlying curl initialization happens only once.

### Function Signature
```rust
pub fn ensure_curl_global_init(api: &CurlApi) -> Result<()>
```

### Parameters
* **api** (*&CurlApi*) - A reference to the CurlApi object, which provides access to curl functionalities.

### Returns
* **Result<()>** - Returns Ok(()) if the initialization is successful or has already been performed. Returns an Err if the initialization fails, propagating the error from the underlying curl_global_init call. Subsequent calls after a failure will return the same error.

### Behavior
- The function guarantees that `curl_global_init` is invoked only a single time during the application's runtime.
- It does not invoke `curl_global_cleanup`, ensuring that the curl library remains loaded until the process terminates.
- If the first invocation of `curl_global_init` results in an error, this error will be consistently returned by all subsequent calls to `ensure_curl_global_init`.
```

--------------------------------

### MultiSession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=

Creates a new MultiSession instance, which is used to manage multiple cURL easy handles concurrently.

```APIDOC
## MultiSession::new

### Description
Creates a new MultiSession instance, which is used to manage multiple cURL easy handles concurrently.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **api** (*&'a CurlApi*) - A reference to the CurlApi object.

### Response
#### Success Response
- **Self** (*Result<Self>*) - A Result containing the new MultiSession instance or an error.

### Request Example
```rust
let api = CurlApi::new();
let multi_session = MultiSession::new(&api)?;
```

### Response Example
```rust
// On success, returns a MultiSession instance.
// On failure, returns an error.
```
```

--------------------------------

### Mutably Iterating Over Ok Value

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Use `iter_mut` to get a mutable iterator that yields a mutable reference to the `Ok` value if present, otherwise yields nothing. Allows in-place modification of the `Ok` value.

```rust
let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### Iterating Over Ok Value

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=std%3A%3Avec

Use `iter` to get an iterator that yields a reference to the `Ok` value if present, otherwise yields nothing. Useful for treating Results like optional values in iteration contexts.

```rust
let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);
```

--------------------------------

### WebSocketConnectConfig

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configuration struct for establishing a WebSocket connection. It allows specifying the target URL, custom headers, an optional proxy, an impersonation target for mimicking browser requests, and a verbose flag for detailed logging.

```APIDOC
## struct WebSocketConnectConfig

### Description
Configuration struct for establishing a WebSocket connection. It allows specifying the target URL, custom headers, an optional proxy, an impersonation target for mimicking browser requests, and a verbose flag for detailed logging.

### Fields
- **url** (`&'a str`): The URL to connect to.
- **headers** (`&'a [String]`): A slice of strings representing the headers to be sent with the request.
- **proxy** (`Option<&'a str>`): An optional proxy server to use for the connection.
- **impersonate_target** (`ImpersonateTarget`): Specifies the target to impersonate for the connection (e.g., a specific browser version).
- **verbose** (`bool`): If true, enables verbose logging for the connection process.
```

--------------------------------

### Collecting Results with Side Effects and Early Exit on Error

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=

Shows how `collect` on a Result iterator stops processing further elements once an Err is encountered. This example verifies that a shared mutable variable only reflects operations performed before the error occurred.

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### MultiSession::new

Source: https://docs.rs/impcurl/1.0.0/impcurl/struct.MultiSession.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new MultiSession instance. This is the entry point for managing multiple cURL transfers concurrently.

```APIDOC
## MultiSession::new

### Description
Creates a new MultiSession instance, which is used to manage multiple cURL easy handles.

### Method
`new`

### Signature
`pub fn new(api: &'a CurlApi) -> Result<Self>`

### Parameters
* `api` (*&'a CurlApi*) - A reference to the CurlApi instance to be used by the MultiSession.
```

--------------------------------

### Global Initialization

Source: https://docs.rs/impcurl/1.0.0/src/impcurl/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Ensures that curl_global_init is called exactly once for the process lifetime. This function does not call curl_global_cleanup, meaning the library remains loaded until the process exits. If the initial call to curl_global_init fails, subsequent calls will return the same error.

```APIDOC
## ensure_curl_global_init

### Description
Ensures that curl_global_init is called exactly once for the process lifetime. This function does not call curl_global_cleanup, meaning the library remains loaded until the process exits. If the initial call to curl_global_init fails, subsequent calls will return the same error.

### Method
```rust
pub fn ensure_curl_global_init(api: &CurlApi) -> Result<()>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Ok(())`: Indicates successful global initialization.

#### Error Response
- `ImpcurlError::Curl`: If `curl_global_init` fails.

### Example
```rust
// Assuming api is an initialized CurlApi struct
match impcurl::ensure_curl_global_init(&api) {
    Ok(_) => println!("Curl global init successful."),
    Err(e) => eprintln!("Curl global init failed: {}", e),
}
```
```

--------------------------------

### Sum of Iterator of Results

Source: https://docs.rs/impcurl/1.0.0/impcurl/type.Result.html?search=

Calculates the sum of elements in an iterator where each element is a Result. If any element is an Err, it's returned immediately. Otherwise, the sum of all Ok values is returned. This example demonstrates summing integers and handling potential errors like negative numbers.

```Rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, 2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Ok(3));
```

```Rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, -2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Err("Negative element found"));
```

--------------------------------

### prepare_connect_only_websocket_session

Source: https://docs.rs/impcurl/1.0.0/impcurl/fn.prepare_connect_only_websocket_session.html?search=

Prepares a WebSocket session for a connection-only scenario. It takes a reference to CurlApi and a WebSocketConnectConfig as input and returns a Result containing an EasySession.

```APIDOC
## Function prepare_connect_only_websocket_session

### Description
Prepares a WebSocket session for a connection-only scenario. It takes a reference to CurlApi and a WebSocketConnectConfig as input and returns a Result containing an EasySession.

### Signature
```rust
pub fn prepare_connect_only_websocket_session<'a>(
    api: &'a CurlApi,
    cfg: &WebSocketConnectConfig<'_>,
) -> Result<EasySession<'a>>
```

### Parameters
* `api` (*&'a CurlApi*) - A reference to the CurlApi object.
* `cfg` (*&WebSocketConnectConfig<'_>*) - A reference to the WebSocket connection configuration.

### Returns
* `Result<EasySession<'a>>` - A Result that is Ok with an EasySession on success, or an Err on failure.
```
Tokens:
Raw