mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-23 00:00:06 +01:00
164 lines
No EOL
12 KiB
TeX
164 lines
No EOL
12 KiB
TeX
\hypertarget{group__Protocols-and-Plugins}{}\section{Protocols and Plugins}
|
|
\label{group__Protocols-and-Plugins}\index{Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsection*{Modules}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
\hyperlink{group__generic-sessions}{plugin\+: generic-\/sessions}
|
|
\end{DoxyCompactItemize}
|
|
\subsection*{Data Structures}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
struct \hyperlink{structlws__protocols}{lws\+\_\+protocols}
|
|
\item
|
|
struct \hyperlink{structlws__plugin__capability}{lws\+\_\+plugin\+\_\+capability}
|
|
\item
|
|
struct \hyperlink{structlws__plugin}{lws\+\_\+plugin}
|
|
\end{DoxyCompactItemize}
|
|
\subsection*{Typedefs}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
typedef int($\ast$ {\bfseries lws\+\_\+plugin\+\_\+init\+\_\+func}) (struct lws\+\_\+context $\ast$, struct \hyperlink{structlws__plugin__capability}{lws\+\_\+plugin\+\_\+capability} $\ast$)\hypertarget{group__Protocols-and-Plugins_ga40994491e1567f91f579d2b444775266}{}\label{group__Protocols-and-Plugins_ga40994491e1567f91f579d2b444775266}
|
|
|
|
\item
|
|
typedef int($\ast$ {\bfseries lws\+\_\+plugin\+\_\+destroy\+\_\+func}) (struct lws\+\_\+context $\ast$)\hypertarget{group__Protocols-and-Plugins_ga83f7a924ba790fa273476075a59f08b0}{}\label{group__Protocols-and-Plugins_ga83f7a924ba790fa273476075a59f08b0}
|
|
|
|
\end{DoxyCompactItemize}
|
|
\subsection*{Functions}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct \hyperlink{structlws__protocols}{lws\+\_\+protocols} $\ast$ \hyperlink{group__Protocols-and-Plugins_ga25754726d97c5f519d313e691a9fe29d}{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol} (struct lws\+\_\+vhost $\ast$vh, const char $\ast$name)
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct \hyperlink{structlws__protocols}{lws\+\_\+protocols} $\ast$ \hyperlink{group__Protocols-and-Plugins_ga72ad550786ca7976463589d347e62112}{lws\+\_\+get\+\_\+protocol} (struct lws $\ast$wsi)
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct \hyperlink{structlws__protocols}{lws\+\_\+protocols} $\ast$ \hyperlink{group__Protocols-and-Plugins_ga8bbe5e65faca068845704bab911a5030}{lws\+\_\+protocol\+\_\+get} (struct lws $\ast$wsi) L\+W\+S\+\_\+\+W\+A\+R\+N\+\_\+\+D\+E\+P\+R\+E\+C\+A\+T\+ED
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN void $\ast$ \hyperlink{group__Protocols-and-Plugins_gaec0c0477288ff3f83aff38d357b883d1}{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc} (struct lws\+\_\+vhost $\ast$vhost, const struct \hyperlink{structlws__protocols}{lws\+\_\+protocols} $\ast$prot, int size)
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN void $\ast$ \hyperlink{group__Protocols-and-Plugins_gaf3be4243443baac0f8be1fcfb4d25129}{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get} (struct lws\+\_\+vhost $\ast$vhost, const struct \hyperlink{structlws__protocols}{lws\+\_\+protocols} $\ast$prot)
|
|
\item
|
|
L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN int \hyperlink{group__Protocols-and-Plugins_ga106b37ae9c247e84d191ab09441adc43}{lws\+\_\+finalize\+\_\+startup} (struct lws\+\_\+context $\ast$context)
|
|
\end{DoxyCompactItemize}
|
|
|
|
|
|
\subsection{Detailed Description}
|
|
\subsubsection*{Protocol and protocol plugin -\/related apis}
|
|
|
|
Protocols bind ws protocol names to a custom callback specific to that protocol implementaion.
|
|
|
|
A list of protocols can be passed in at context creation time, but it is also legal to leave that N\+U\+LL and add the protocols and their callback code using plugins.
|
|
|
|
Plugins are much preferable compared to cut and pasting code into an application each time, since they can be used standalone.
|
|
|
|
\subsection{Function Documentation}
|
|
\index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+finalize\+\_\+startup@{lws\+\_\+finalize\+\_\+startup}}
|
|
\index{lws\+\_\+finalize\+\_\+startup@{lws\+\_\+finalize\+\_\+startup}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+finalize\+\_\+startup(struct lws\+\_\+context $\ast$context)}{lws\_finalize\_startup(struct lws\_context *context)}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN int lws\+\_\+finalize\+\_\+startup (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws\+\_\+context $\ast$}]{context}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_ga106b37ae9c247e84d191ab09441adc43}{}\label{group__Protocols-and-Plugins_ga106b37ae9c247e84d191ab09441adc43}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_ga106b37ae9c247e84d191ab09441adc43}{lws\+\_\+finalize\+\_\+startup()} -\/ drop initial process privileges
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em context} & lws context\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
This is called after the end of the vhost protocol initializations, but you may choose to call it earlier \index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+get\+\_\+protocol@{lws\+\_\+get\+\_\+protocol}}
|
|
\index{lws\+\_\+get\+\_\+protocol@{lws\+\_\+get\+\_\+protocol}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+get\+\_\+protocol(struct lws $\ast$wsi)}{lws\_get\_protocol(struct lws *wsi)}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct {\bf lws\+\_\+protocols}$\ast$ lws\+\_\+get\+\_\+protocol (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws $\ast$}]{wsi}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_ga72ad550786ca7976463589d347e62112}{}\label{group__Protocols-and-Plugins_ga72ad550786ca7976463589d347e62112}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_ga72ad550786ca7976463589d347e62112}{lws\+\_\+get\+\_\+protocol()} -\/ Returns a protocol pointer from a websocket connection.
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em wsi} & pointer to struct websocket you want to know the protocol of\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
\begin{DoxyVerb} Some apis can act on all live connections of a given protocol,
|
|
this is how you can get a pointer to the active protocol if needed.\end{DoxyVerb}
|
|
\index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+protocol\+\_\+get@{lws\+\_\+protocol\+\_\+get}}
|
|
\index{lws\+\_\+protocol\+\_\+get@{lws\+\_\+protocol\+\_\+get}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+protocol\+\_\+get(struct lws $\ast$wsi) L\+W\+S\+\_\+\+W\+A\+R\+N\+\_\+\+D\+E\+P\+R\+E\+C\+A\+T\+ED}{lws\_protocol\_get(struct lws *wsi) LWS\_WARN\_DEPRECATED}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct {\bf lws\+\_\+protocols}$\ast$ lws\+\_\+protocol\+\_\+get (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws $\ast$}]{wsi}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_ga8bbe5e65faca068845704bab911a5030}{}\label{group__Protocols-and-Plugins_ga8bbe5e65faca068845704bab911a5030}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_ga8bbe5e65faca068845704bab911a5030}{lws\+\_\+protocol\+\_\+get()} -\/ deprecated\+: use lws\+\_\+get\+\_\+protocol \index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get@{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get}}
|
|
\index{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get@{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get(struct lws\+\_\+vhost $\ast$vhost, const struct lws\+\_\+protocols $\ast$prot)}{lws\_protocol\_vh\_priv\_get(struct lws\_vhost *vhost, const struct lws\_protocols *prot)}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN void$\ast$ lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws\+\_\+vhost $\ast$}]{vhost, }
|
|
\item[{const struct {\bf lws\+\_\+protocols} $\ast$}]{prot}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_gaf3be4243443baac0f8be1fcfb4d25129}{}\label{group__Protocols-and-Plugins_gaf3be4243443baac0f8be1fcfb4d25129}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_gaf3be4243443baac0f8be1fcfb4d25129}{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+get()} -\/ retreive a protocol\textquotesingle{}s per-\/vhost storage
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em vhost} & vhost the instance is related to \\
|
|
\hline
|
|
{\em prot} & protocol the instance is related to\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
Recover a pointer to the allocated per-\/vhost storage for the protocol created by \hyperlink{group__Protocols-and-Plugins_gaec0c0477288ff3f83aff38d357b883d1}{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc()} earlier \index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc@{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc}}
|
|
\index{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc@{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc(struct lws\+\_\+vhost $\ast$vhost, const struct lws\+\_\+protocols $\ast$prot, int size)}{lws\_protocol\_vh\_priv\_zalloc(struct lws\_vhost *vhost, const struct lws\_protocols *prot, int size)}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN void$\ast$ lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws\+\_\+vhost $\ast$}]{vhost, }
|
|
\item[{const struct {\bf lws\+\_\+protocols} $\ast$}]{prot, }
|
|
\item[{int}]{size}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_gaec0c0477288ff3f83aff38d357b883d1}{}\label{group__Protocols-and-Plugins_gaec0c0477288ff3f83aff38d357b883d1}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_gaec0c0477288ff3f83aff38d357b883d1}{lws\+\_\+protocol\+\_\+vh\+\_\+priv\+\_\+zalloc()} -\/ Allocate and zero down a protocol\textquotesingle{}s per-\/vhost storage
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em vhost} & vhost the instance is related to \\
|
|
\hline
|
|
{\em prot} & protocol the instance is related to \\
|
|
\hline
|
|
{\em size} & bytes to allocate\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
Protocols often find it useful to allocate a per-\/vhost struct, this is a helper to be called in the per-\/vhost init L\+W\+S\+\_\+\+C\+A\+L\+L\+B\+A\+C\+K\+\_\+\+P\+R\+O\+T\+O\+C\+O\+L\+\_\+\+I\+N\+IT \index{Protocols and Plugins@{Protocols and Plugins}!lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol@{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol}}
|
|
\index{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol@{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol}!Protocols and Plugins@{Protocols and Plugins}}
|
|
\subsubsection[{\texorpdfstring{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol(struct lws\+\_\+vhost $\ast$vh, const char $\ast$name)}{lws\_vhost\_name\_to\_protocol(struct lws\_vhost *vh, const char *name)}}]{\setlength{\rightskip}{0pt plus 5cm}L\+W\+S\+\_\+\+V\+I\+S\+I\+B\+LE L\+W\+S\+\_\+\+E\+X\+T\+E\+RN const struct {\bf lws\+\_\+protocols}$\ast$ lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol (
|
|
\begin{DoxyParamCaption}
|
|
\item[{struct lws\+\_\+vhost $\ast$}]{vh, }
|
|
\item[{const char $\ast$}]{name}
|
|
\end{DoxyParamCaption}
|
|
)}\hypertarget{group__Protocols-and-Plugins_ga25754726d97c5f519d313e691a9fe29d}{}\label{group__Protocols-and-Plugins_ga25754726d97c5f519d313e691a9fe29d}
|
|
|
|
|
|
{\ttfamily \#include $<$\hyperlink{libwebsockets_8h}{lib/libwebsockets.\+h}$>$}
|
|
|
|
\hyperlink{group__Protocols-and-Plugins_ga25754726d97c5f519d313e691a9fe29d}{lws\+\_\+vhost\+\_\+name\+\_\+to\+\_\+protocol()} -\/ get vhost\textquotesingle{}s protocol object from its name
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em vh} & vhost to search \\
|
|
\hline
|
|
{\em name} & protocol name\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
Returns N\+U\+LL or a pointer to the vhost\textquotesingle{}s protocol of the requested name |